, ,
/( )\
| \ / | "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.
The public v7 MCP surface is guided and workspace-scoped:
- Guided mode automatically briefs an unbriefed session on
memory_recall,memory_preflight,memory_store, ormemory_record_outcome, returningmeta.covenant.auto_brief. Diagnostic and discovery calls do not trigger briefing. Callsession_brieffor the full brief. - Call
memory_store(or any protected tool) directly. If it returnsCOUNSEL_REQUIRED, readerror.counsel(guidance and reasons), then retry exactlyerror.remedy.memory_preflightremains available for planning a change in advance. - Use
daem0n_tools_search(query), thendaem0n_tool_call(workspace_id, tool, arguments).
The default listing contains nine tools; all 77 remain registered and callable.
Set DAEM0NMCP_TOOL_SURFACE=full to list every tool, or
DAEM0NMCP_COVENANT_MODE=strict to require explicit briefing and preflight.
Tokens remain exact-argument bound, single-use, and valid for 300 seconds.
Destructive operations always require a counsel challenge. Linked workspaces
still require their own explicit session_brief; task submission stays strict.
Run long-running targets directly as MCP tasks, using the full listing if
needed; the gateway does not submit tasks. Use system_health for diagnostics.
The server states this protocol itself: the MCP initialize result carries
instructions generated for the active covenant mode and tool listing.
Each scoped call uses an opaque workspace_id. The supported transports are
stdio and Streamable HTTP at /mcp. Read-only warnings, failures, rules, and
active context use the memory://workspaces/{workspace_id}/... resources. See
docs/v6-to-v7-tools.json for the generated
migration mapping.
v7 is not published yet. Until release, install from a source checkout or a wheel you built from this checkout:
pip install .
# or: python -m build && pip install dist/daem0nmcp-7.0.0.dev0-py3-none-any.whlAfter v7 is published, pip install daem0nmcp will install the small core.
Add only the feature profiles the deployment needs: tasks, local, graph,
apps, models-local, late-interaction, models-hosted, agency-e2b, or observability.
For example, pip install "daem0nmcp[apps,graph]". The development and
compatibility profiles (dev and tracing) are not required by a normal MCP
server. models-local and late-interaction are optional and require Python
3.11 or newer. Their secure ONNX runtime dependency has no CPython 3.10 wheel.
On Python 3.10, the resolver omits these profiles' dependencies and the runtime
reports Python-version remediation while core installation remains supported.
The server owns workspace registration. Set DAEM0NMCP_PROJECT_ROOT to the
default workspace and, when needed, DAEM0NMCP_WORKSPACE_ROOTS to the allowed
additional roots. Operators obtain the stable opaque ID from the local CLI
and provide it in the protected client configuration or pairing flow;
session_brief then confirms that ID. Use the local workspace-id CLI to inspect
the project's recorded identity; do not recalculate an ID after moving an existing
workspace. Clients do not choose filesystem paths. Leave
DAEM0NMCP_STORAGE_PATH unset when serving multiple registered workspaces.
A workspace ID is an identifier, not a secret. New IDs derive from the canonical root path, while a moved workspace can retain its recorded ID. Read the current identity with the CLI rather than inferring it from the current path. "Opaque" means only that it is not a path and carries no meaning for clients. Access is decided by the authenticated principal and its grants, never by knowledge of the ID.
For authenticated remote principals, set DAEM0NMCP_WORKSPACE_ACCESS_FILE to
the server-managed grants file. If unset, the server uses
<managed-storage>/v7-workspace-access.json. The file and its parent directory
must be owner-only. Its strict JSON shape is
{"schema_version":1,"grants":{"oauth-sub:<subject>":["ws_<opaque>"]}};
the server rereads it at authorization points, so removing a grant takes effect
without a restart. The CLI has no grant-editing command: configure the file and
environment before launching python -m daem0nmcp.server.
Start the stdio server with python -m daem0nmcp.server, or use
python -m daem0nmcp.server --transport streamable-http --host 127.0.0.1 --port 9876 for loopback HTTP. A remote HTTP deployment requires configured transport
authentication and security policy; it is not a redirect-based setup.
Loopback HTTP without FASTMCP_SERVER_AUTH does not authenticate callers: every
process and user that can reach the port on that host (other accounts,
containers, WSL) acts as the server's own principal on every registered
workspace. On a shared machine use stdio or configure authentication. A
loopback listener behind a reverse proxy is not local: when
DAEM0NMCP_TRUSTED_PROXY_IPS is set or DAEM0NMCP_ALLOWED_HOSTS names a host
other than localhost or a loopback address, the server refuses to start with
PROXIED_LISTENER_REQUIRES_AUTH unless a production token verifier is
configured. That check sees a proxy only through those two settings. A proxy
that forwards the loopback authority as Host (for example nginx without
proxy_set_header Host $host) needs neither, is not detected, and exposes the
unauthenticated listener to its clients, so configure authentication for every
proxied deployment.
python -m resolves daem0nmcp from the current directory first, so type these
commands (and the python -m daem0nmcp.cli ones) from a directory you trust.
Commands that a host launches for you inside a project never use -m: the
installers and the registration command drop
the current directory from the import path first.
The complete setup, exact preflight examples, migrations, native client installers, diagnostics, and all 77 registered v7 tools are in the v7 operations guide. The release ledger remains in progress; these instructions do not claim a published v7 release.
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 for format 6 — existing format-6 embeddings must be re-encoded with the deprecated legacy command:
python -m daem0nmcp.migrations.migrate_embedding_model --project-path /path/to/.daem0nmcpArchitecture format 7 does not write canonical memories.vector_embedding data.
Rebuild its dense retrieval projection instead:
python -m daem0nmcp.cli rebuild-projection --projection dense --workspace-id <workspace-id>When the user goes idle, the daemon autonomously re-evaluates past failed decisions using current evidence:
IdleDreamSchedulermonitors tool call activity- After configurable idle timeout (default 60s),
FailedDecisionReviewstrategy runs - Classifies decisions as revised, confirmed_failure, or needs_more_data
- Insights persisted as
learningmemories withdreamtag and full provenance - Yields immediately when user returns (cooperative scheduling)
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 |
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
New daem0nmcp/claude_hooks/ module with 5 lifecycle hooks and automated installation:
python -m daem0nmcp.cli install-claude-hooks # Install to ~/.claude/settings.json
python -m daem0nmcp.cli uninstall-claude-hooks # Remove| Hook | Purpose |
|---|---|
session_start |
Explain automatic briefing and optional full session_brief |
pre_edit |
Remind agents to recall file guidance through daem0n_tool_call |
pre_bash |
Rule enforcement on bash commands |
post_edit |
Suggest replay-safe memory calls for significant changes |
stop |
Suggest memory and outcome calls without writing directly |
- 8 workflow tools + 3 cognitive tools (11 MCP tools total)
- 59 workflow actions across 8 workflows
- 500+ tests passing
v5.1 consolidates 67 individual MCP tools into 8 workflow-oriented tools, dramatically reducing context overhead for AI agents while preserving all capabilities.
| 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 |
Format 6 grouped individual operations behind an action discriminator. Those
calls are not executable v7 guidance. Use the generated
docs/v6-to-v7-tools.json mapping for the exact
replacement of every old operation.
- 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 functions remain importable for internal dispatch, but only the consolidated workflow and cognitive tools are exposed to MCP clients
This v6 release added interactive HTML interfaces via MCP Apps (SEP-1865). Those action-dispatch examples are intentionally omitted because they are not valid v7 calls; use the generated migration mapping for current tool names.
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.
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_timevstransaction_time),happened_atbackfilling,as_of_timepoint-in-time queries, contradiction detection - Metacognitive Reflexion: Actor-Evaluator-Reflector loop,
verifyaction validates claims against stored knowledge, reflection persistence - Context Engineering: LLMLingua-2 for 3x-6x compression, code entity preservation, adaptive rates,
compressaction for on-demand optimization - Dynamic Agency:
executeaction for sandboxed Python execution via E2B Firecracker microVMs
- 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
- CovenantMiddleware: Sacred Covenant enforcement via FastMCP 3.0 middleware pattern
- Component Versioning: All tools include version metadata
- OpenTelemetry Tracing (Optional):
pip install daem0nmcp[tracing]
v2.16.0 — Sacred Covenant Enforcement
- Tools block with
COMMUNION_REQUIRED/COUNSEL_REQUIREDuntil proper rituals observed - Preflight tokens with 5-minute validity
- MCP Resources for dynamic context injection (the retired URI forms are
mapped to v7 in
docs/v6-to-v7-tools.json)
v2.14.0–v2.15.0 — Active Context, Temporal Versioning, Entities
- Active Working Context (MemGPT-style always-hot memories, max 10)
- Temporal versioning with
versionsandat_timequeries - 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
v2.11.0–v2.13.0 — Passive Capture, Linked Projects
- Passive Capture hooks (auto-remember decisions from conversation)
- Endless Mode (condensed recall with 50-75% token reduction)
- Linked Projects for cross-repo memory awareness
v2.7.0–v2.10.0 — Code Understanding, Enforcement, File Watcher
- 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
Core Features (v2.1+)
- 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
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.
- 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
-
Copy Summon_Daem0n.md into the project you want Daem0n to remember.
-
Open your selected AI CLI in that project and say:
Read Summon_Daem0n.md and perform the complete summoning ritual for this project.
-
Let the AI inspect the machine, install the source checkout into a dedicated environment, configure the workspace and its native MCP connection, preserve project instructions, and verify the result. Complete the host's trust or restart handoff when requested, then ask it to resume the ritual.
The grimoire selects the current host, or the one named in your request. It does not register every CLI found on the machine.
| Host | Project installation | Native MCP config |
|---|---|---|
Claude Code (claude) |
Claude branch of the grimoire, including maintained reminder hooks | .mcp.json |
Codex (codex) |
install-client codex |
.codex/config.toml |
Antigravity CLI (agy) |
install-client agy |
.agents/mcp_config.json |
OpenCode V1 (opencode) |
install-client opencode |
opencode.json(c) or .opencode/opencode.json(c) |
OpenCode V2 (opencode) |
install-client opencode --opencode-interface v2 --client-version <version> |
V2 mcp.servers in its own project configuration |
Oh My Pi (omp) |
install-client omp |
.omp/mcp.json |
Earendil Works Pi (pi) |
install-client pi |
.pi/mcp.json |
The project client installer adds native MCP registration and a concise owned
covenant in the effective instruction file: normally AGENTS.md, a Codex
override/project fallback, or OpenCode's existing CLAUDE.md fallback. It preserves
unrelated configuration and comments, reports backups/conflicts, and leaves
global settings, provider credentials and permission policies alone. Omitting
--automation preserves the previous MCP-only installation behavior. Select
--automation off|remind|enforce explicitly to manage supported project hooks
or edit-bridge pairing. Unsupported enforcement requests fail before modifying
the project. See native automation for version
requirements and covered tools, and client installation
for configuration examples. Guided memory calls return the automatic brief for
an unbriefed session; instruction loading, reminders, and native edit enforcement
have separate acceptance evidence.
Client support is version-specific. Real Windows client tests passed the core memory workflow, restart recall and replay checks on Codex 0.167.0, agy 1.4.7, OpenCode 1.18.21, omp 18.16.0 and Earendil Works Pi 1.0.0. See the source-backed Codex/agy, OpenCode and OMP/Pi findings for feature and acceptance boundaries. OpenCode V2 has a different schema and requires separate integration evidence. Actual setup and live-client results are recorded in the historical multi-CLI acceptance report. The native integration follow-up separately records real-source indexing, automation, Windows/macOS/Ubuntu WSL evidence, frozen backend builds, failed workflows and external blockers.
For agy, keep your normal Google-account sign-in. A Gemini API key is a separate,
optional billing route. To use Google AI credits after your included quota runs
out, enable Use AI Credits in agy's /settings or /config; /credits
shows the balance. Daem0n's installer does not change this spending preference.
See Antigravity's credit instructions.
The file is a self-contained instruction manual for the AI. Copying it alone
does not execute it. The default ritual uses Python 3.12 when available,
project-scoped stdio on Windows, macOS and Linux, and the local, graph,
apps, and models-local extras. These local models need downloads and disk
space; the grimoire also covers an explicitly requested small-core setup.
E2B cloud execution, Redis tasks and telemetry are optional, not setup
prerequisites. Existing memories, unrelated settings and other MCP servers
are preserved. Authentication and the selected host's trust prompts may require
your participation; the AI must report those handoffs instead of claiming success.
After the grimoire's source/environment and workspace-ID steps, run from the
trusted source checkout using its dedicated interpreter. Replace <CLIENT>
with one of codex, agy, opencode, omp or pi, and pass the selected
client's observed --version output:
<VENV_PYTHON> -m daem0nmcp.cli --project-path "<PROJECT>" --json install-client <CLIENT> --client-version "<OBSERVED_VERSION>" --dry-run
<VENV_PYTHON> -m daem0nmcp.cli --project-path "<PROJECT>" --json install-client <CLIENT> --client-version "<OBSERVED_VERSION>"
Review the returned file actions and complete the normal host trust/restart flow. Configuration recognition is followed by actual brief, health, write, recall, outcome and restart checks from the grimoire. For OpenCode-specific protocol details, see its companion.
For the complete install, existing-data migration, upgrade and verification sequence, use the grimoire. These commands show the package installation portion from a trusted source directory:
# Clone the repository
git clone https://github.com/9thLevelSoftware/Daem0n-MCP.git "$HOME/Daem0n-MCP"
cd "$HOME/Daem0n-MCP"
# macOS/Linux; use the selected Python 3.11 or 3.12 interpreter
python3.12 -m venv .venv
.venv/bin/python -m pip install -e '.[local,graph,apps,models-local]'# Windows, from the source checkout
py -3.12 -m venv .venv
& .\.venv\Scripts\python.exe -m pip install -e '.[local,graph,apps,models-local]'Stdio is the default, including on Windows. The selected native MCP host starts and stops the server; no separate terminal, port, Startup shortcut or background service is needed. Codex, agy, OpenCode V1, omp and pi use the project installer above. For Claude Code, run registration from the target project, using the absolute path of the installed virtual environment's interpreter and the absolute project root:
claude mcp add daem0nmcp --scope project --transport stdio -e "DAEM0NMCP_PROJECT_ROOT=<PROJECT_ROOT>" -- "<PYTHON_PATH>" -c "import sys; sys.path = [p for p in sys.path if p]; import runpy; runpy.run_module('daem0nmcp.server', run_name='__main__', alter_sys=True)"If a Daem0n entry already exists, follow the grimoire's inspect-and-merge flow
instead of deleting it. Obtain the workspace selector with the installed
interpreter's python -m daem0nmcp.cli --json workspace-id, with
DAEM0NMCP_PROJECT_ROOT set to the same project. Store the returned ID in the
project protocol, then restart Claude Code and approve the project server when
prompted. Run session_brief and system_health with that ID before the
grimoire's write/recall/restart acceptance checks.
Do not register <PYTHON_PATH> -m daem0nmcp.server. Claude Code
starts the server inside the opened project, and python -m
puts that directory first on sys.path, so a repository that contains its own
daem0nmcp/ directory would run in place of the installed server. The command
above runs the same module after dropping the working directory from the import
path; it works on Python 3.10 and newer and with --user, virtualenv and
editable installs. Use the full interpreter path rather than a bare python.
The command leaves your own PYTHONPATH alone. An empty or relative element in
it (a leading or trailing :, or .) names the working directory, which puts
the opened project back on the import path: keep PYTHONPATH unset or absolute
in the environment your MCP host starts from.
Use HTTP when you deliberately want a separately managed server. It is not a
Windows requirement. Set DAEM0NMCP_PROJECT_ROOT in the server's environment
before starting it from a trusted directory with the installed interpreter:
python -m daem0nmcp.server --transport streamable-http --host 127.0.0.1 --port 9876Merge this entry into the target project's existing .mcp.json:
{
"mcpServers": {
"daem0nmcp": {
"type": "http",
"url": "http://127.0.0.1:9876/mcp"
}
}
}Start Claude Code after the HTTP server is ready. Keep storage derived per workspace. Remote or shared-host HTTP requires the authentication configuration described in the operations guide; local stdio needs no network listener.
| Method | Transport | Default Port | Use Case |
|---|---|---|---|
python -m daem0nmcp.server |
stdio |
n/a | Local process channel |
python start_server.py |
Streamable HTTP at /mcp |
9876 | Optional separately managed HTTP server |
python -m daem0nmcp.server is for a terminal you started yourself. When an MCP
host launches the stdio server for you, register the command from
Stdio instead: hosts start it inside
whatever project is open.
For the five other CLI hosts, use the project-scoped client installer. OpenCode's optional legacy plugin workflow is described under OpenCode Integration.
The v7 public API uses strict input schemas and opaque workspace scope. The default core-plus-gateway listing is:
| Tool | Purpose |
|---|---|
session_brief |
Return the full briefing; guided memory calls automatically brief an unbriefed session |
memory_preflight |
Plan ahead with guidance and a capability for one exact protected request |
memory_recall |
Retrieve bounded, evidence-bearing records |
memory_store |
Append one replay-safe memory record |
memory_record_outcome |
Append a verified success or failure outcome |
system_health |
Return bounded service and projection diagnostics |
edit_preflight |
Admit native edit-bridge requests |
daem0n_tools_search |
Discover other registered tools and their input schemas |
daem0n_tool_call |
Call a discovered tool and relay its guidance or result |
daem0n_tool_call can reach destructive, non-idempotent and open-world tools,
so it advertises destructiveHint: true, idempotentHint: false and
openWorldHint: true; a host that prompts on those hints prompts for every
gateway call. Each daem0n_tools_search result carries the target's own
read_only, destructive, idempotent and open_world hints.
The read-only JSON resources are:
memory://workspaces/{workspace_id}/warningsmemory://workspaces/{workspace_id}/failuresmemory://workspaces/{workspace_id}/rulesmemory://workspaces/{workspace_id}/active-context
A read returns application/json. Every refusal (an unknown workspace, one the
caller may not read, or one this session has not briefed) is the same JSON-RPC
error, code -32002 with the message Resource unavailable; brief the
workspace first.
See docs/v6-to-v7-tools.json for the generated
mapping of every v6 operation to its v7 replacement.
| 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) |
| 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 |
| 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 |
| Action | Purpose |
|---|---|
outcome |
Record whether a decision worked or failed |
verify |
Validate factual claims against stored knowledge |
execute |
Sandboxed Python execution (E2B) |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
Recognize only the exact canonical name or its host prefix:
| Canonical | Claude Code | OpenCode |
|---|---|---|
session_brief |
mcp__daem0nmcp__session_brief |
daem0nmcp_session_brief |
memory_preflight |
mcp__daem0nmcp__memory_preflight |
daem0nmcp_memory_preflight |
memory_recall |
mcp__daem0nmcp__memory_recall |
daem0nmcp_memory_recall |
memory_store |
mcp__daem0nmcp__memory_store |
daem0nmcp_memory_store |
memory_record_outcome |
mcp__daem0nmcp__memory_record_outcome |
daem0nmcp_memory_record_outcome |
system_health |
mcp__daem0nmcp__system_health |
daem0nmcp_system_health |
daem0n_tools_search |
mcp__daem0nmcp__daem0n_tools_search |
daem0nmcp_daem0n_tools_search |
daem0n_tool_call |
mcp__daem0nmcp__daem0n_tool_call |
daem0nmcp_daem0n_tool_call |
Host metadata is never an identity source. Authentication comes from the
transport, and every scoped request is resolved through workspace_id.
Codex, agy and Pi may expose tools through lazy discovery or a native wrapper.
Use the client's discovered daem0nmcp server and exact v7 tool basename, keeping
arguments and structured counsel/remedy fields intact. A missing direct tool
name does not establish that a lazy tool is unavailable. MCP resource browsing
and rich app rendering are separate host capabilities; they are not implied by
a successful memory tool call.
Guided memory_recall returns a compact automatic brief for an unbriefed session. Request the full brief
explicitly when needed:
session_brief(
workspace_id="<workspace_id>",
focus_areas=["authentication", "API"]
)
memory_recall(
workspace_id="<workspace_id>",
query="authentication",
limit=10,
token_budget=2400
)
Call directly; no preflight is needed for a benign write in guided mode:
memory_store(
workspace_id="<workspace_id>",
record_type="decision",
content="Use signed session cookies",
rationale="Avoid server-side session state",
tags=["auth", "architecture"],
relative_file_path="src/auth/session.py",
idempotency_key="decision-auth-session-0001"
)
If the response is COUNSEL_REQUIRED, review error.counsel, then call
error.remedy.tool with exactly error.remedy.arguments. The remedy already
includes its pre-minted token. memory_preflight remains available for advance
planning and is required in strict mode. Keep the idempotency key on retries.
Every failed call, COUNSEL_REQUIRED included, is an ok: false envelope and
sets the MCP result's isError: true. The envelope is still delivered in full,
as structuredContent and as JSON text; a client library that raises on
isError must be told to return the result instead so the remedy can be read.
memory_record_outcome(
workspace_id="<workspace_id>",
record_id="<mem_id>",
outcome_text="The implementation passed integration tests",
worked=true,
idempotency_key="outcome-auth-session-0001"
)
The recommended workflow for AI agents:
memory_recall or memory_preflight (automatic brief in guided mode)
-> memory_recall (when relevant)
-> protected tool directly
-> review error.counsel and retry error.remedy (only when challenged)
-> memory_record_outcome (after verification, replay-safe)
Use system_health for bounded diagnostics. The complete protocol lives in
AGENTS.md and .claude/skills/daem0nmcp-protocol/SKILL.md.
python -m daem0nmcp.cli install-claude-hooksFor explicit project automation, use --project-path <project> before
install-claude-hooks, followed by --automation off|remind|enforce.
Enforcement additionally requires --client-version <observed-version> at
2.1.295 or later. Explicit modes write the project's local settings; omitting
the option retains the user-level behavior described below.
This writes the packaged hook entries to the user-level ~/.claude/settings.json, so
they run in every project; each runs daem0nmcp.claude_hooks.<hook>
with the interpreter you installed from. A hook only acts inside a Daem0n
project: the session directory, CLAUDE_PROJECT_DIR, or one of their parent
directories contains .daem0nmcp/ (your home directory does not count, since
Daem0n keeps its own state in ~/.daem0nmcp/). Other hooks in that file are kept, and any old
hooks/daem0n_*.py entries are removed.
Each command is "<python>" -c "<bootstrap>": the bootstrap drops the working
directory from sys.path and then runs the hook module, so a repository that
contains its own daem0nmcp/ directory cannot replace the installed hooks the
way it could with python -m. Commands written by an earlier version keep the
-m form until you re-run install-claude-hooks, which replaces them and
reports how many it replaced; until then the SessionStart hook shows a
one-line reminder in every session. The same PYTHONPATH limit as for the
registration command applies.
The installer currently uses the operating-system home directory, not
CLAUDE_CONFIG_DIR. The grimoire handles custom Claude configuration directories
by generating and merging the Daem0n hook entries into the actual settings file.
| Event (matcher) | Hook | What it does | Input | Reminds only |
|---|---|---|---|---|
SessionStart |
session_start |
Explains guided memory calls auto-brief an unbriefed session; diagnostics and discovery do not; session_brief returns the full brief |
CLAUDE_PROJECT_DIR env |
Yes |
PreToolUse (Edit|Write|NotebookEdit) |
pre_edit |
Inside a Daem0n project, adds a one-line additionalContext reminder to call daem0n_tool_call targeting memory_recall_file; silent elsewhere |
stdin event | Yes |
PreToolUse (Bash) |
pre_bash |
Checks the command against active Daem0n rules (governance_rules / rules) in read-only SQLite mode and emits matching additionalContext reminders |
stdin event (TOOL_INPUT fallback) |
Yes (always exits 0) |
PostToolUse (mcp__.*__edit_preflight) |
post_edit_preflight |
Retained edit-bridge plumbing: stages a receipt for an explicit host-created request. The current remind-only hooks create no requests, so pairing alone does not activate this flow | stdin event | Yes |
PostToolUse (Edit|Write|NotebookEdit) |
post_edit |
Retained edit-bridge plumbing: reports an approved edit as a capture candidate. The current remind-only hooks create no requests, so ordinary client edits produce no bridge capture | stdin event | Yes |
Stop, SubagentStop |
stop |
When the transcript shows a finished task with no recorded outcome, suggests direct memory_store and memory_record_outcome calls with counsel-challenge retry guidance as a systemMessage. Never writes memory |
stdin event (transcript_path) |
Yes |
The reminder behavior in this table applies to the legacy installation with
--automation omitted and to explicit reminder mode. It does not block edits
or keep the agent running. Explicit --automation enforce enables the
native edit gate for its declared edit tools.
What optional pairing writes. When --enable-edit-bridge (or explicit remote bridge flags) are passed, the installer also pairs the current project (or
--project-path) with the local edit bridge:
- an owner-only credential at
~/.daem0nmcp/edit-bridges/<authority>/credential.json(the secret is never written into the project), with the bridge socket under~/.daem0nmcp/edit-bridges/run/<authority[:16]>/, or a protected short per-user temporary endpoint when the Unix socket path would be too long; - the env keys
DAEM0NMCP_EDIT_BRIDGE_CREDENTIAL_FILE,DAEM0NMCP_EDIT_BRIDGE_RUNTIME_DIR,DAEM0NMCP_PROJECT_ROOTandDAEM0NMCP_STORAGE_PATHin<project>/.claude/settings.local.json.
To remove the hooks, the project's pairing env keys (only if the installer paired it) and, optionally, its credential (the project defaults to the current directory):
python -m daem0nmcp.cli uninstall-claude-hooks [--project-path <project>] [--remove-credentials]The old manual scripts in hooks/ are deprecated stubs that only print a
notice and exit 0. If your settings still point at them, re-run
install-claude-hooks.
A Claude Code skill is included at .claude/skills/daem0nmcp-protocol/SKILL.md that enforces the memory protocol automatically.
OpenCode V1 connects through its native MCP manager. For a new project use
install-client opencode from Quick Start, then finish the
grimoire's real MCP and restart verification. The new installer creates the
project binding and managed covenant without requiring the legacy plugin.
The legacy/default V1 plugin provides Covenant guidance and edit/Bash reminders.
Explicit install-client opencode --automation enforce installs the native
deny/preflight/retry flow for declared edit tools. See
native automation for coverage and version
requirements, and the native acceptance report
for observed host behavior.
For inspecting an existing V1 entry, the shape is below. Replace the interpreter and project placeholders with absolute paths; the project installer performs the preserving merge for a new registration:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"daem0nmcp": {
"type": "local",
"command": ["<PYTHON_PATH>", "-E", "-u", "-X", "utf8", "-c", "import sys; sys.path = [p for p in sys.path if p]; import runpy; runpy.run_module('daem0nmcp.server', run_name='__main__', alter_sys=True)"],
"cwd": "<PROJECT>",
"enabled": true,
"environment": {
"PYTHONPATH": "",
"DAEM0NMCP_PROJECT_ROOT": "<PROJECT>",
"DAEM0NMCP_COVENANT_MODE": "guided",
"DAEM0NMCP_TOOL_SURFACE": "core"
}
}
}
}The command is the cwd-free equivalent of python -m daem0nmcp.server: OpenCode starts
the server inside the opened project, and -m would import a daem0nmcp/
directory found there. install-client opencode fixes the interpreter to the
dedicated environment it runs under. Its -E flag ignores inherited Python import
settings before startup, including hosts that discard empty environment overrides.
It does not replace unrelated servers or provider settings. Public OpenCode V2
docs use mcp.servers/disabled; this V1 example must not be copied into V2.
For a separately managed Streamable HTTP server, use:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"daem0nmcp": {
"type": "remote",
"url": "http://localhost:9876/mcp",
"enabled": true
}
}
}OpenCode reads AGENTS.md from the project root, with CLAUDE.md as a fallback.
The installer adds the covenant to the existing effective file so that it does
not hide the project's other instructions.
If both AGENTS.md and CLAUDE.md exist in a project, OpenCode uses only AGENTS.md.
The older install-opencode command scaffolds the V1 plugin and can provision
edit-bridge pairing. It is separate from install-client opencode and is not
required for core memory functionality. Inspect its dry-run and existing files
before choosing it. In particular, --force overwrites configuration and can
discard other MCP servers; do not use it as an automatic upgrade path. Existing
plugins and shortcuts may be retained while their own behavior is verified.
OpenCode uses a different tool name format than Claude Code:
| Client | Format | Example |
|---|---|---|
| Claude Code | mcp__servername__toolname |
mcp__daem0nmcp__session_brief |
| OpenCode | servername_toolname |
daem0nmcp_session_brief |
Both formats resolve to the same MCP server tools. Use the exact form matching your client. See Tool Names by Client.
- 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"
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
weight = e^(-lambda*t) where lambda = ln(2)/half_life_days
Default half-life is 30 days. Patterns and warnings are permanent (no decay).
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
Memories with worked=False get a 1.5x relevance boost in recalls.
Warnings get a 1.2x boost. Past mistakes surface prominently.
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.
Each project gets isolated storage at:
<project_root>/.daem0nmcp/storage/daem0nmcp.db
<project_root>/.daem0nmcp/workspace-id records which workspace those rows
belong to, so the memories follow the folder when it is moved or renamed. Move
the whole folder, .daem0nmcp/ included; re-clone by copying .daem0nmcp/ into
the new clone. Two registered folders may not claim one identity — settle a
copy with python -m daem0nmcp.cli --project-path <root> workspace-id --new.
See docs/v7-operations.md for the full rules.
All settings are configurable via environment variables with DAEM0NMCP_ prefix.
A .env file in the working directory is not read: the server is usually
launched inside a project, so that file belongs to the repository, not to the
operator. To keep settings in a file, set DAEM0NMCP_ENV_FILE to its absolute
path in the server's environment. A relative path or a missing file is refused
at startup, and real environment variables override values from the file.
That file may hold only the settings listed in the tables below. Any other
line stops startup, including variables the server reads straight from its
environment: the transport and proxy settings (DAEM0NMCP_ALLOWED_HOSTS,
DAEM0NMCP_ALLOWED_ORIGINS, DAEM0NMCP_TRUSTED_PROXY_IPS),
DAEM0NMCP_WORKSPACE_ACCESS_FILE, DAEM0NMCP_TOKEN_SECRET, the
DAEM0NMCP_EDIT_BRIDGE_* and task variables, and every FASTMCP_* variable.
Keep those in the process environment.
The FastMCP library has its own .env loading for FASTMCP_* settings. The
server turns it off by setting FASTMCP_ENV_FILE to the null device when it is
unset, so a project's .env cannot change them either. To load FASTMCP_*
settings from a file, set FASTMCP_ENV_FILE yourself to an absolute path; a
relative value is resolved against the working directory. Authentication
variables (FASTMCP_SERVER_AUTH*) are read only from the process environment.
| 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) |
| 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 |
| 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_LEXICAL_CONTENT_TIERING |
false |
Rank content/rationale matches ahead of tag-assisted matches in lexical recall |
DAEM0NMCP_SEARCH_DIVERSITY_MAX_PER_FILE |
3 |
Max results from same file |
| 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 |
| 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 |
| 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 |
| 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 automatic setup and feature choices, and the v7 operations guide for deployment settings.
daem0nmcp/
├── api/v7/ # Strict v7 models, handlers, policy, and adapters
├── server.py # MCP server composition and transport entry point
├── 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)
├── 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/ # Legacy v6 compatibility implementation (migration only)
│ ├── 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 # Legacy v6 workflow definitions (migration only)
│ ├── 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 # Suggest scoped v7 briefing
│ ├── pre_edit.py # Remind-only file recall guidance
│ ├── pre_bash.py # Read-only command-rule reminders
│ ├── post_edit.py # Retained edit-bridge capture reporting
│ ├── stop.py # Read-only outcome/memory suggestions
│ └── _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 # Host shortcut for session_brief
│ ├── counsel.md # Host shortcut for memory_preflight
│ ├── inscribe.md # Host shortcut for memory_store
│ └── recall.md # Host shortcut for memory_recall
└── plugins/
└── daem0n.ts # Covenant enforcement plugin
Summon_Daem0n.md # Complete host-selecting installation grimoire
Summon_Daem0n_OpenCode.md # OpenCode V1 protocol and binding companion
Banish_Daem0n.md # Uninstallation instructions (both clients)
start_server.py # HTTP server launcher (streamable-http transport)
# 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; vector backfill is format 6 only)
python -m daem0nmcp.cli migrate [--backfill-vectors]
# Inspect a v7 retrieval projection
python -m daem0nmcp.cli projection-status --workspace-id <workspace_id>
# Rebuild a v7 retrieval projection from canonical events
python -m daem0nmcp.cli rebuild-projection --projection dense --workspace-id <workspace_id># Register one native CLI host in the selected project (from trusted source cwd)
python -m daem0nmcp.cli --project-path /path/to/project install-client codex --client-version 0.167.0 --dry-run
# Replace codex with agy, opencode, omp or pi and use its observed version.
# Omit --dry-run after inspecting the proposed owned changes.
# 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]
# Optional legacy OpenCode V1 plugin/bridge scaffolding (inspect before use)
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
Use MCP memory_record_outcome for v7 outcomes. It requires an opaque
workspace_id, a v7 record_id, and a stable idempotency key.
Ask the selected AI CLI to read the current Summon_Daem0n.md and resume the ritual. It inventories the existing installation, preserves data and configuration, upgrades the selected environment, refreshes its own integration entries, and verifies persistence. It does not reset a workspace or overwrite unrelated settings. Use the following notes for manual maintenance.
# Inspect before updating; retain local work and record the prior revision.
cd "$HOME/Daem0n-MCP"
git status --short --branch
git rev-parse HEAD
# With a clean checkout on the intended branch:
git pull --ff-only
# Use the existing environment's Python and the previously selected extras.
.venv/bin/python -m pip install -e '.[local,graph,apps,models-local]'On Windows use & .\.venv\Scripts\python.exe for the final command. Stop
affected Daem0n processes before upgrading their environment or migrating their
storage; do not terminate unrelated Python or Claude processes.
The embedding model changed from all-MiniLM-L6-v2 (384-dim) to nomic-ai/modernbert-embed-base (256-dim).
Deprecated (format 6 only): These legacy writers update the mutable
memories.vector_embeddingcolumn or legacy Qdrant collections. They refuse an active format-7 database before making changes.
# Re-encode the format-6 SQLite column (and local Qdrant, when present)
python -m daem0nmcp.migrations.migrate_embedding_model --project-path /path/to/.daem0nmcp
# Copy existing format-6 SQLite vectors to legacy Qdrant
python -m daem0nmcp.migrations.migrate_vectors --project-path /path/to/project
# Backfill missing format-6 SQLite vectors
python -m daem0nmcp.cli --project-path /path/to/project migrate --backfill-vectorsFor architecture format 7, rebuild the dense retrieval projection from canonical events. Supply the registered workspace ID reported by the v7 migration/status commands:
python -m daem0nmcp.cli rebuild-projection --projection dense --workspace-id <workspace-id>python -m daem0nmcp.cli install-claude-hooksRe-run this after upgrading. It replaces the hook commands earlier versions
wrote, including the python -m form that imports a daem0nmcp/ directory
from any project you open. If you registered the stdio server at user scope as
<PYTHON_PATH> -m daem0nmcp.server, remove it with
claude mcp remove daem0nmcp --scope user and register the command under
Installation by Platform instead. In repositories
where you ran install-hooks, re-run it as well: the git pre-commit hook it
wrote used python -m too.
After updating, restart/reconnect the selected CLI to load the new MCP binding and tools, completing its normal trust prompt. Resume the grimoire's affected protocol and persistence checks.
<VENV_PYTHON> -m daem0nmcp.cli --project-path "<PROJECT>" --json install-client <CLIENT> --client-version "<OBSERVED_VERSION>" --dry-run
For Codex, agy, OpenCode V1, omp or pi, inspect this dry-run with the same
project and selected host. Equivalent entries remain unchanged. A different
interpreter, stale root or custom existing binding may require a scoped,
backup-backed update after inspecting the reported conflict. Preserve unrelated
configuration and existing data. Do not replace the file with a template or run
the legacy OpenCode installer's --force as a shortcut.
A format 7 database is never upgraded in place. When a newer build needs a
newer schema, the server and the legacy commands answer MIGRATION_REQUIRED
until migrate-v7 --apply has run; that command snapshots the store first and
can be rolled back. A retained format 6 database only receives format 6 schema
migrations. If active-db.json is lost, commands answer
ACTIVE_POINTER_MISSING; see docs/v7-operations.md for
migrate-v7 --recover-pointer.
Moving an existing v6 workspace to the v7 storage format is not automatic.
It is an offline, reversible command, and a v6 workspace answers
MIGRATION_REQUIRED until it has run:
# Stop the server first, then:
python -m daem0nmcp.cli --project-path /path/to/project migrate-v7 --apply
# Undo it; refuses if events were recorded since activation unless
# --discard-v7-writes is passed.
python -m daem0nmcp.cli --project-path /path/to/project migrate-v7 --rollbackpython -m daem0nmcp.cli indexSupports Python, TypeScript, JavaScript, Go, Rust, Java, C, C++, C#, Ruby, PHP via tree-sitter.
memory_store.informed_by and memory_record_outcome.informed_by accept up to
32 existing record IDs in the same workspace. They record explicit provenance;
recall remains read-only. Outcomes may include
verification={"kind": "test", "command": "pytest", "exit_code": 0}; verification
is caller-reported evidence, not a command executed by the server.
Schema 33 derives learning signals and provenance from canonical events. The v7 upgrader restores missing derived record parents only after complete canonical authority replay succeeds, then backfills learning evidence in the same transaction. Invalid authority fails closed; failed upgrades leave the active database and pointer unchanged.
Utility ranking defaults to shadow: it reports estimates and diagnostics
without changing retrieval order. Shadow still computes those estimates and can
add database work and query latency; use off to skip that computation. Opt in
to ranking changes with:
DAEM0NMCP_RETRIEVAL_UTILITY_MODE=apply
DAEM0NMCP_RETRIEVAL_UTILITY_CREDIT=tracesingle_step uses immediate outcome credit; trace also propagates bounded,
discounted credit through explicit provenance. The default ranking weight is
0.1. Set DAEM0NMCP_RETRIEVAL_UTILITY_MODE=off to disable computation. Failed
decisions remain warnings rather than being demoted by their own failures.
Utility only reorders candidates whose rank prior and fused score are within 5%
of each other, so outcome history breaks near-ties and never outranks a clearly
better match.
memory_store.code_refs accepts up to 16
{"relative_file_path": "src/x.py", "qualified_name": "f"} references.
Omit qualified_name to bind the whole file. Qualified names select a specific
symbol; a bare name binds every matching declaration in that file. Fingerprints
ignore CRLF/LF differences, and symbol bindings ignore edits to sibling symbols.
The server manages context.code_bindings; callers cannot set it themselves.
Recall reports applicability (current, needs_revalidation, or
unverifiable) and changed_bindings. Parser unavailability is not proof that
code changed. The default validity mode is shadow; set
DAEM0NMCP_MEMORY_VALIDITY_MODE=apply to include revalidation labels in context,
or off to skip checks. After checking changed code, record a successful
outcome with rebind_code=true to refresh existing bindings.
memory_recall accepts an optional intent: explore, implement, debug,
or review. Implement/debug retention reserves room for procedures and matching
code bindings, with shorter ordinary excerpts; review also bounds stale guidance.
The default DAEM0NMCP_RETRIEVAL_RETENTION_MODE=shadow computes retention diagnostics
without changing context or ranking. Set it to apply to change evidence packing,
or off to skip computation. Without an intent, context packing is unchanged.
These settings also apply to linked-workspace recall.
Install pip install "daem0nmcp[late-interaction]" and set:
DAEM0NMCP_RETRIEVAL_RERANK_ENABLED=true
DAEM0NMCP_RETRIEVAL_RERANKER=late_interactionRequest memory_recall(..., rerank=true). The default model is
colbert-ir/colbertv2.0, configured by
DAEM0NMCP_RETRIEVAL_LATE_INTERACTION_MODEL. It loads lazily and may download
weights on first use; warm the model before measuring latency. Cold downloads
can exceed the provider timeout (DAEM0NMCP_QDRANT_TIMEOUT_SECONDS) and report
RERANKER_FAILED while preserving the original order. An unavailable profile
reports RERANKER_UNAVAILABLE; it never silently substitutes embedding reranking.
Symptom: claude mcp list shows daem0nmcp connected, but Claude can't use mcp__daem0nmcp__* tools.
Fixes:
- Inspect
claude mcp listandclaude mcp get daem0nmcpfrom the target project. Check the configured interpreter, transport and project root. - Restart Claude Code after configuration changes and complete its project server trust prompt. A running session does not automatically gain tools from a newly written configuration file.
- For stdio, let Claude Code launch the configured process. For deliberately
configured HTTP, start that server first and verify its
/mcpendpoint with an MCP client. Do not switch transports just because the host is Windows. - Resume the grimoire's diagnostics; retain other MCP entries and inspect local/project/user scope conflicts before changing registration.
- Check the hook commands in Claude's actual user settings and any project
settings; ensure their interpreter still exists. See the custom
CLAUDE_CONFIG_DIRnote above. - Check that the project has a
.daem0nmcp/directory and that hook events identify the expected project. - Hooks remind; they do not block edits or write memories automatically. MCP server connectivity is a separate check.
COMMUNION_REQUIRED→ Callsession_brief(workspace_id="<workspace_id>")firstCOUNSEL_REQUIRED→ Follow the returned remedy and callmemory_preflight(workspace_id="<workspace_id>", target_tool="<exact-tool>", target_arguments={<exact-arguments>})
Symptom: OpenCode reports "tool not found" when using mcp__daem0nmcp__* format.
Fix: OpenCode uses the exact single-underscore form
daem0nmcp_session_brief; Claude Code uses
mcp__daem0nmcp__session_brief. See Tool Names by Client.
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.
Symptom: No preflight warnings, no post-edit suggestions in OpenCode.
Fix:
- Verify plugin exists:
ls .opencode/plugins/daem0n.ts - Verify AGENTS.md contains the Sacred Covenant section
- Check OpenCode logs for plugin errors
# 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 9876python -m benchmarks.coding_memory_eval --mode lexical_only --topics 24 --seed 20261004 --output coding-eval.json
# Optional real-provider comparison (install local, models-local, graph and late-interaction):
python -m benchmarks.coding_memory_eval --mode fully_enabled --topics 24 --seed 20261004 --output coding-eval-full.jsonThis isolated synthetic workload exercises outcome reuse, multi-hop provenance, symbol/file validity and budgeted procedure retention through the production writer and recall service. The lexical mode requires no model downloads. Event times are assigned in write order, not read from the wall clock, and the seed only shuffles the order of the writes: every seed reports the same metrics, so repeating a run with other seeds adds no evidence. Latency measurements are wall-clock and excluded from deterministic comparisons. Each run creates its own temporary directory and removes it when it ends, so concurrent runs never share storage and a directory left by a killed run does not block the next one.
Reports expose all arm settings. Utility weight is 0.2 in the evaluation
(the product default stays 0.1). Retention distractors are same-category
background procedure drafts with task tags: this prevents category diversity
from automatically rescuing the actionable procedure and tests actual packing
under a 256-token budget. Every arm uses the product default for lexical content
tiering (off) except tiering_apply and all_apply_tiering, which turn it on:
with the tier the procedure already ranks first, so those two arms retain the
required fact without the retention policy and cannot show its effect. These
synthetic gains are not a competitor comparison.
The release-frozen retrieval corpus and its digest remain unchanged.
bash autoresearch.sh runs the same offline lexical workload with 24 topics,
seed 20261004 and a fixed event clock, emitting METRIC coding_memory_ndcg
(higher is better) plus ranking, retention, validity and token metrics. A fresh
offline MCP workspace also reports listed_tool_count, guided_write_calls,
strict_explicit_write_calls and destructive_challenge_calls. The strict
workload separately verifies rejection of an unbriefed direct write before
measuring the explicit briefing/preflight/write flow; destructive call counts
exclude the selection preview. It uses the project virtual environment and
excludes wall-clock latency.
If Daem0nMCP has been useful to you, consider supporting its development:
See Banish_Daem0n.md for complete removal instructions (covers both Claude Code and OpenCode), or quick version:
python -m daem0nmcp.cli uninstall-claude-hooks
claude mcp remove daem0nmcp --scope user
pip uninstall daem0nmcp
rm -rf ~/Daem0n-MCP
rm -rf .daem0nmcp/rm opencode.json
rm -rf .opencode/commands/ .opencode/plugins/daem0n.ts
pip uninstall daem0nmcp
rm -rf ~/Daem0n-MCP
rm -rf .daem0nmcp/ "The system learns from YOUR outcomes.
Record them faithfully..."
~ Daem0n
Daem0nMCP v7 development: persistent memory, replay-safe decisions and outcomes, workspace-scoped tools, and optional local search, models, graphs and visual portals. Read the grimoire. Complete the ritual. Verify what awakened.