Daemon-MCP

# Daem0n-MCP FastMCP 3.0 Tool Audit ## Executive Summary **Date:** 2026-01-21 **Version Audited:** 3.0.0 **Total Tools:** 53 ### FastMCP 3.0 Compatibility Status | Status | Count | Description | |--------|-------|-------------| | Compliant | 53 | All tools have `@mcp.tool(version="3.0.0")` | | Middleware | 1 | CovenantMiddleware properly integrated | | Deprecated | 0 | Legacy decorators removed from server.py | ### Critical Issues Found 1. ~~**Token Efficiency (WIP)**~~ - RESOLVED: Truncation committed in 92cf884 2. ~~**Blocking Operations**~~ - RESOLVED: `index_project` now uses `asyncio.to_thread()` (issue #40) ### High-Priority Enhancements 1. ~~Remove duplicate covenant enforcement~~ - RESOLVED: Decorators removed (issue #39) 2. Add FTS5 for faster full-text search 3. Incremental code indexing 4. Background tasks for long operations ### Efficiency Quick Wins 1. Cache TF-IDF index vectors 2. Batch vector operations 3. Compile regex patterns once 4. Use read-write locks for contexts --- **Audit Date:** 2026-01-21 **FastMCP Version:** 3.0.0b1+ **Daem0n-MCP Version:** 3.0.0 ## Overview This document tracks the audit of all 53 MCP tools for FastMCP 3.0 compliance following the upgrade from FastMCP 2.x. --- ## CovenantMiddleware **File:** `daem0nmcp/transforms/covenant.py` **Registration:** `daem0nmcp/server.py:200-212` **Test File:** `tests/test_covenant_transform.py` (25 tests) ### FastMCP 3.0 Compliance - VERIFIED - [X] **ToolResult construction** - VERIFIED - Uses `ToolResult(content=[mt.TextContent(type="text", text=...)])` (line 522) - Correctly imports `from fastmcp.tools import ToolResult` (line 405) - Correctly imports `from mcp import types as mt` (line 406) - [X] **Middleware inheritance** - VERIFIED - Inherits from `fastmcp.server.middleware.Middleware` (line 417) - Correctly imports `from fastmcp.server.middleware import Middleware, MiddlewareContext, CallNext` (line 404) - Uses proper type hints: `context: MiddlewareContext[mt.CallToolRequestParams]` (line 482) - [X] **call_next() signature** - VERIFIED - Signature: `call_next: CallNext[mt.CallToolRequestParams, ToolResult]` (line 483) - Invocation: `return await call_next(context.message)` (line 526) - Passes the message object, not the context wrapper - [X] **Middleware registration** - VERIFIED - Uses `mcp.add_middleware(middleware)` pattern (server.py line 206) - Conditional registration with `_FASTMCP_MIDDLEWARE_AVAILABLE` flag - Graceful fallback to decorator-based enforcement when middleware unavailable - [X] **Graceful import handling** - VERIFIED - Try/except block for FastMCP middleware imports (lines 403-414) - Defines stub types when middleware is unavailable - `_FASTMCP_MIDDLEWARE_AVAILABLE` flag exported for consumers ### Test Coverage - EXCELLENT All 25 tests pass: - Transform logic tests (14 tests): tool classification, blocking behavior, TTL expiry - Middleware tests (6 tests): inheritance, method presence, blocking via transform, allowing valid requests - Server integration tests (5 tests): middleware registration, state callback, briefing flow ### Architecture Notes 1. **Two-layer design:** - `CovenantTransform` - Pure logic for covenant enforcement (no FastMCP dependencies) - `CovenantMiddleware` - FastMCP 3.0 adapter wrapping the transform 2. **State management:** - State callback pattern via `get_state: Callable[[Optional[str]], Optional[Dict[str, Any]]]` - Per-project tracking via `_project_contexts` dict in server.py - `_get_context_state_for_middleware()` bridges server state to middleware 3. **Tool classification:** - `COVENANT_EXEMPT_TOOLS` - Read-only and entry point tools (27 tools) - `COMMUNION_REQUIRED_TOOLS` - Tools requiring prior `get_briefing()` (26 tools) - `COUNSEL_REQUIRED_TOOLS` - Tools requiring prior `context_check()` (9 tools) ### Technical Enhancements (Future) - [ ] Consider adding OpenTelemetry spans for covenant violations - Traces already enabled (per recent commit `40c0ea4`) - Could add `span.set_attribute("covenant.violation", violation_type)` - [ ] Add rate limiting for repeated covenant violations - Currently logs violations but doesn't throttle misbehaving clients - Consider exponential backoff or temporary blocking ### Efficiency Improvements (Low Priority) - [ ] Cache tool classification lookups - Set membership is already O(1), so impact is minimal - Could pre-compute classification at middleware init time ### Deprecation Notice The decorator-based enforcement (`@requires_communion`, `@requires_counsel`) is deprecated: - Warning appears in test output (51 warnings) - Decorators still function for backwards compatibility - `CovenantMiddleware` now handles all enforcement at the MCP layer --- ## Remaining Tools to Audit The following tool categories remain to be audited for FastMCP 3.0 compliance: ### Memory Tools - [X] remember - AUDITED (see Memory Tools) - [X] remember_batch - AUDITED (see Memory Tools) - [X] recall - AUDITED (see Memory Tools) - [X] recall_for_file - AUDITED (see Memory Tools) - [X] search_memories - AUDITED (see Advanced Memory Tools) - [X] find_related - AUDITED (see Advanced Memory Tools) - [X] pin_memory - AUDITED (see Data Management Tools) - [X] archive_memory - AUDITED (see Data Management Tools) - [X] prune_memories - AUDITED (see Context & Workflow Tools) - [X] cleanup_memories - AUDITED (see Data Management Tools) - [X] compact_memories - AUDITED (see Context & Workflow Tools) ### Rule Tools - [X] add_rule - AUDITED (see Rules Engine Tools) - [X] check_rules - AUDITED (see Rules Engine Tools) - [X] list_rules - AUDITED (see Rules Engine Tools) - [X] update_rule - AUDITED (see Rules Engine Tools) ### Outcome Tracking - [X] record_outcome - AUDITED (see Covenant Flow Tools) ### Session Tools - [X] get_briefing - AUDITED (see Covenant Flow Tools) - [X] context_check - AUDITED (see Covenant Flow Tools) - [X] health - AUDITED (see Remaining Tools) ### Code Intelligence - [X] index_project - AUDITED (see Code Understanding Tools) - [X] find_code - AUDITED (see Code Understanding Tools) - [X] analyze_impact - AUDITED (see Code Understanding Tools) - [X] scan_todos - AUDITED (see Remaining Tools) - [X] propose_refactor - AUDITED (see Remaining Tools) ### Graph Operations - [X] link_memories - AUDITED (see Covenant Flow Tools) - [X] unlink_memories - AUDITED (see Covenant Flow Tools) - [X] trace_chain - AUDITED (see Community & Entity Tools) - [X] get_graph - AUDITED (see Remaining Tools) ### Community Detection - [X] rebuild_communities - AUDITED (see Community & Entity Tools) - [X] list_communities - AUDITED (see Community & Entity Tools) - [X] get_community_details - AUDITED (see Community & Entity Tools) - [X] recall_hierarchical - AUDITED (see Advanced Memory Tools) ### Entity Tracking - [X] recall_by_entity - AUDITED (see Advanced Memory Tools) - [X] list_entities - AUDITED (see Community & Entity Tools) - [X] backfill_entities - AUDITED (see Code Understanding Tools) ### Context Triggers - [X] add_context_trigger - AUDITED (see Remaining Tools) - [X] list_context_triggers - AUDITED (see Remaining Tools) - [X] remove_context_trigger - AUDITED (see Remaining Tools) - [X] check_context_triggers - AUDITED (see Remaining Tools) ### Active Context - [X] set_active_context - AUDITED (see Context & Workflow Tools) - [X] get_active_context - AUDITED (see Context & Workflow Tools) - [X] remove_from_active_context - AUDITED (see Context & Workflow Tools) - [X] clear_active_context - AUDITED (see Context & Workflow Tools) ### Time Travel - [X] get_memory_versions - AUDITED (see Context & Workflow Tools) - [X] get_memory_at_time - AUDITED (see Context & Workflow Tools) ### Project Linking - [X] link_projects - AUDITED (see Remaining Tools) - [X] unlink_projects - AUDITED (see Remaining Tools) - [X] list_linked_projects - AUDITED (see Remaining Tools) - [X] consolidate_linked_databases - AUDITED (see Remaining Tools) ### Import/Export - [X] export_data - AUDITED (see Data Management Tools) - [X] import_data - AUDITED (see Data Management Tools) - [X] ingest_doc - AUDITED (see Remaining Tools) ### Index Maintenance - [X] rebuild_index - AUDITED (see Data Management Tools) --- ## Project Context Management **Files:** `daem0nmcp/server.py:125-520`, `daem0nmcp/database.py:1-220`, `daem0nmcp/active_context.py` ### FastMCP 3.0 Compliance - VERIFIED - [X] **Context management compatible with middleware** - VERIFIED - `ProjectContext` dataclass properly structured with all required fields (line 128-142) - Includes `briefed` and `context_checks` fields for covenant state tracking - Per-project isolation via normalized path keys in `_project_contexts` dict - [X] **Middleware callback `_get_context_state_for_middleware` correctly integrated** - VERIFIED - Function at lines 175-198 returns correct structure: `{"briefed": bool, "context_checks": list}` - Handles None project_path gracefully (returns None) - Bridges `_get_context_for_covenant()` to middleware requirements - Registered with `CovenantMiddleware` at server startup (lines 201-211) - [X] **Context eviction does not interfere with middleware state** - VERIFIED - `active_requests` counter prevents eviction while tools are in-flight (line 138) - Two-phase eviction approach avoids nested lock acquisition (lines 435-518) - Task tracking via `_track_task_context()` ensures requests complete before eviction - Lock ordering: contexts_lock -> individual ctx.lock (prevents deadlocks) - [X] **Multi-project isolation works with middleware** - VERIFIED - Each project has isolated `ProjectContext` with own managers - Path normalization ensures consistent cache keys (`_normalize_path()`) - Middleware receives project_path from tool arguments, looks up correct context - No cross-project state leakage possible ### DatabaseManager Compliance - VERIFIED - [X] **Async session management** - VERIFIED - Uses `async_sessionmaker` with `AsyncSession` (line 69-73) - Lazy engine creation for correct event loop context (line 39-74) - Proper transaction handling in `get_session()` context manager (lines 128-139) - [X] **Connection pooling appropriate for SQLite** - VERIFIED - Uses `NullPool` to avoid connection issues across async contexts (line 47) - SQLite PRAGMAs configured for performance: WAL mode, NORMAL sync, 30s busy timeout - [X] **Lifecycle management** - VERIFIED - `init_db()` creates tables and runs migrations (lines 103-126) - `close()` properly disposes engine and resets state (lines 213-219) - Called during context eviction (`await ctx.db_manager.close()`) ### Architecture Notes 1. **Double-checked locking pattern:** - Fast path checks `_project_contexts` without lock (line 358) - Slow path acquires project-specific lock for initialization - Second check after lock acquisition prevents race conditions (line 380) 2. **LRU + TTL eviction policy:** - TTL eviction: contexts older than `CONTEXT_TTL_SECONDS` (default 3600) - LRU eviction: oldest contexts when over `MAX_PROJECT_CONTEXTS` (default 10) - Opportunistic scheduling via `_maybe_schedule_eviction()` with 60s cooldown 3. **Task context tracking:** - `_task_contexts` dict maps asyncio tasks to project usage counts - Done callback automatically releases contexts when tasks complete - Prevents eviction of contexts with in-flight requests 4. **Covenant state in ProjectContext:** - `briefed: bool` - Set True after `get_briefing()` called - `context_checks: List[Dict]` - Timestamped check records for TTL tracking ### Technical Enhancements (Future) - [ ] **Add context lifecycle hooks for middleware reset** - Currently middleware state persists until context eviction - Could add `reset_covenant_state()` method for explicit session boundaries - Use case: Long-running clients that want fresh covenant state - [ ] **Consider moving covenant state to separate dataclass** - `CovenantState` dataclass with `briefed`, `context_checks`, `last_briefing_time` - Cleaner separation between context management and covenant enforcement - Would simplify `_get_context_state_for_middleware()` implementation - [ ] **Add metrics for context eviction events** - OpenTelemetry already integrated (commit `40c0ea4`) - Add spans for: context creation, eviction (TTL vs LRU), lifecycle duration - Useful for capacity planning and debugging stale context issues ### Efficiency Improvements (Low Priority) - [ ] **LRU eviction runs opportunistically - consider background task** - Current: Eviction triggered during `get_project_context()` calls - Impact: Slight latency spike when eviction runs - Alternative: Periodic background task every 60s - Trade-off: Adds complexity, marginal benefit for typical workloads - [ ] **Context lock contention under high load - consider read-write locks** - Current: `asyncio.Lock` for all operations (exclusive access) - Impact: Serial access to same project context - Alternative: `asyncio.RWLock` (readers don't block each other) - Trade-off: Most operations are reads (recall, search), but standard library lacks RWLock - Recommendation: Evaluate if high-concurrency scenarios emerge - [ ] **Path normalization called repeatedly** - `_normalize_path()` resolves symlinks on every context lookup - Impact: Filesystem syscall per tool invocation - Alternative: Cache resolved paths in LRU dict - Trade-off: Symlink changes wouldn't be detected until cache expires ### Code Quality Notes 1. **Clean error handling:** - `_missing_project_path_error()` provides helpful error messages - `_resolve_within_project()` validates paths stay within project root - Graceful handling of invalid paths with clear error messages 2. **Memory safety:** - Contexts properly closed on eviction (`await ctx.db_manager.close()`) - Orphaned locks cleaned up in Phase 4 of eviction (lines 513-517) - No memory leaks observed in extended testing 3. **Thread safety:** - All shared state protected by appropriate locks - No race conditions in context initialization (double-checked locking) - Task-based tracking handles concurrent requests correctly --- ## Deprecated Decorators (covenant.py) **File:** `daem0nmcp/covenant.py:440-596` **Test File:** `tests/test_covenant.py` (14 tests) ### FastMCP 3.0 Issues - VERIFIED - [X] **Decorators deprecated but functional** - VERIFIED - `_deprecated_decorator_warning()` helper emits `DeprecationWarning` at decoration time (line 444-452) - `@requires_communion` decorator (line 488-523) - emits warning via `_deprecated_decorator_warning("requires_communion")` - `@requires_counsel` decorator (line 526-596) - emits warning via `_deprecated_decorator_warning("requires_counsel")` - Warning message includes FastMCP 3.0 migration guidance - Uses `stacklevel=4` to point to the decorator application site - [X] **Fallback enforcement works** - VERIFIED - Decorators still apply full enforcement logic when middleware unavailable - 14 tests in `tests/test_covenant.py` all pass - State retrieval via `_get_context_callback` and `_get_context_state()` functions - [X] **No conflicts with middleware** - VERIFIED ("belt and suspenders" works) - Middleware enforces at MCP layer (before tool function is called) - Decorators enforce inside tool function (if middleware passes) - Double-enforcement is harmless - both check same state - When middleware blocks, decorator is never reached - When middleware allows, decorator re-validates (redundant but safe) ### Test Coverage - GOOD All 14 tests pass in `tests/test_covenant.py`: - Violation response structure (2 tests) - Preflight token generation and validation (4 tests) - CovenantEnforcer class (7 tests) - Integration with server (1 test) 51 deprecation warnings emitted during test run (expected behavior). ### Deprecation Timeline - [ ] **v3.0** (current): Decorators deprecated with warnings, still functional - [ ] **v4.0** (proposed): Consider removal of decorator-based enforcement - Depends on FastMCP 3.0 middleware stability - Monitor for any environments where middleware is unavailable ### Technical Enhancements (Future) - [ ] **Decorator-to-middleware forwarding** - Could replace decorator logic with simple middleware invocation - Would eliminate duplicate enforcement code - Trade-off: Adds FastMCP dependency to decorators ### Efficiency Improvements - [ ] **Remove duplicate enforcement** (decorators + middleware) - Current: Both layers check same conditions - Impact: ~2x redundant state lookups per protected tool call - Severity: Low (lookups are cheap dict operations) - Recommendation: Leave as-is until v4.0 removal ### Code Quality Notes 1. **Clean deprecation pattern:** - Centralized warning helper (`_deprecated_decorator_warning`) - Clear migration message mentioning `CovenantMiddleware` - Appropriate stacklevel for accurate warning locations 2. **Backwards compatibility maintained:** - Decorators applied to 51 tools in server.py - All continue to function during transition period 3. **Belt-and-suspenders safety:** - If middleware is bypassed or fails silently, decorators catch violations - Defense in depth until decorator removal is safe --- ## Memory Tools **Files:** `daem0nmcp/server.py:544-700`, `daem0nmcp/memory.py:163-664` **Test File:** `tests/test_memory.py` (29 tests for remember/recall) ### remember **Server Definition:** `daem0nmcp/server.py:546-584` **Implementation:** `daem0nmcp/memory.py:330-488` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 546) - Return type is `Dict[str, Any]` (correct for FastMCP JSON serialization) - No raw exceptions - returns error dict for invalid category (line 357) - Returns error dict for missing project_path via `_missing_project_path_error()` (line 573) - Project path handling via `get_project_context()` with proper normalization - [X] **Decorators applied** - VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_counsel` - Covenant enforcement (deprecated, backed by middleware) - [X] **Test Coverage** - EXCELLENT - `test_remember_decision` - Basic decision storage - `test_remember_warning` - Warning with permanent flag - `test_remember_invalid_category` - Error handling ### Technical Enhancements (Future) - [ ] **Add memory deduplication on store** - Currently no check for duplicate content+category+file_path - Could hash content and check for exact duplicates - Trade-off: Added latency on write vs. potential storage savings - [ ] **Batch vector indexing for faster storage** - Currently vectors indexed one-by-one during `remember()` - Qdrant supports batch upsert (already used in `remember_batch`) - Single-memory case could benefit from deferred indexing --- ### remember_batch **Server Definition:** `daem0nmcp/server.py:590-628` **Implementation:** `daem0nmcp/memory.py:490-664` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 590) - Return type is `Dict[str, Any]` with structured response - Returns partial success on batch errors (already implemented - lines 628-633) - Returns `created_count`, `error_count`, `ids`, `errors` for transparency - Project path handling correct via `get_project_context()` - [X] **Decorators applied** - VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_counsel` - Covenant enforcement - [X] **Test Coverage** - EXCELLENT (9 tests) - `test_batch_creates_multiple_memories` - Basic batch creation - `test_batch_with_tags` - Tag preservation - `test_batch_empty_list` - Edge case handling - `test_batch_invalid_category` - Partial failure handling - `test_batch_missing_content` - Validation errors - `test_batch_all_invalid` - Complete failure case - `test_batch_atomic_success` - Transaction atomicity - `test_batch_with_file_paths` - File association - `test_batch_preserves_rationale` - Field preservation ### Technical Enhancements (Future) - [ ] **Return partial success on batch errors** - ALREADY IMPLEMENTED - Validation errors don't abort entire batch (lines 531-545) - Per-memory errors tracked with index for debugging - Response includes both successes and failures - [ ] **Single transaction for all batch items** - ALREADY IMPLEMENTED - Uses single `async with self.db.get_session()` block (line 555) - All valid memories committed atomically - Qdrant upserts also batched within same loop ### Efficiency Improvements (Low Priority) - [ ] **Pre-validate all memories before any DB writes** - Current: Validates during write loop, errors skip individual items - Alternative: Two-pass validation (validate all -> write all) - Trade-off: Slightly cleaner but more memory for large batches --- ### recall **Server Definition:** `daem0nmcp/server.py:634-696` **Implementation:** `daem0nmcp/memory.py:828-1080` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 634) - Return type is `Dict[str, Any]` with categorized results - Returns error dict for invalid date formats (lines 675, 681) - Returns error dict for missing project_path - `condensed=True` parameter implemented for token reduction (line 648) - [X] **Decorators applied** - VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_communion` - Requires prior `get_briefing()` call - [X] **Test Coverage** - EXCELLENT (15 tests) - `test_recall_by_topic` - Basic semantic search - `test_recall_by_category` - Category filtering - `test_recall_includes_relevance_scores` - Score metadata - `test_recall_with_tag_filter` - Tag-based filtering - `test_recall_with_file_filter` - File path filtering - `test_recall_with_combined_filters` - Multiple filters - `test_recall_pagination_offset` - Offset pagination - `test_recall_pagination_has_more` - Pagination metadata - `test_recall_pagination_offset_beyond_total` - Edge cases - `test_recall_date_filter_since` - Date range (since) - `test_recall_date_filter_until` - Date range (until) - `test_recall_date_range_filter` - Combined date range - `test_recall_cache_hit` - Caching behavior - `test_recall_cache_invalidated_on_remember` - Cache invalidation - `test_recall_cache_invalidated_on_outcome` - Cache invalidation ### Technical Enhancements (Future) - [ ] **Add `condensed=True` parameter** - ALREADY IMPLEMENTED - Strips rationale and context fields (lines 875-876) - Truncates content for token reduction - Reduces output by ~75% for large result sets ### Efficiency Improvements - [ ] **Cache TF-IDF results with TTL** - ALREADY IMPLEMENTED - `get_recall_cache()` provides 5-second TTL caching (line 882) - Cache key includes all filter parameters (line 883-889) - Cache invalidated on `remember()` and `record_outcome()` calls - Recall count still incremented on cache hits for saliency tracking - [ ] **Hybrid search with Qdrant vectors** - ALREADY IMPLEMENTED - `_hybrid_search()` combines TF-IDF and vector similarity (lines 257-328) - Configurable vector weight via `settings.hybrid_vector_weight` - Graceful fallback to TF-IDF when Qdrant unavailable --- ### recall_for_file **Server Definition:** `daem0nmcp/server.py:2015-2036` **Implementation:** `daem0nmcp/memory.py:1420-1540` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 2015) - Return type is `Dict[str, Any]` with categorized results - Returns error dict for missing project_path - Project path handling correct via `get_project_context()` - [X] **Decorators applied** - VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_communion` - Requires prior `get_briefing()` call - [X] **Implementation Details** - REVIEWED - Queries both `file_path` (absolute) and `file_path_relative` columns - Also searches for filename mentions in content/rationale - Deduplicates results from direct association and mentions - Returns results organized by category (decisions, patterns, warnings, learnings) - Used by enforcement system to check files before commits ### Technical Enhancements (Future) - [ ] **Support glob patterns for file matching** - Currently only exact path matching - Could use `fnmatch` for patterns like `src/**/*.py` - Use case: Get memories for all files in a directory - Trade-off: Query complexity vs. flexibility ### Efficiency Improvements - [ ] **Index file paths for O(1) lookup** - Currently uses SQL LIKE queries for filename matching (lines 1481-1492) - Could add B-tree index on `file_path` column - Could add trigram index for LIKE queries - Trade-off: Index maintenance cost vs. query speed - Recommendation: Profile before optimizing (likely not a bottleneck) - [ ] **Cache file-to-memory mapping** - File path lookups are deterministic until memories change - Could cache results with invalidation on `remember()` or `archive_memory()` - Trade-off: Memory usage vs. repeated file access speed --- ## Memory Tools Summary | Tool | FastMCP 3.0 | Return Type | Error Handling | Tests | |------|-------------|-------------|----------------|-------| | remember | [X] v3.0.0 | Dict[str, Any] | Error dicts | 3 | | remember_batch | [X] v3.0.0 | Dict[str, Any] | Partial success | 9 | | recall | [X] v3.0.0 | Dict[str, Any] | Error dicts | 15 | | recall_for_file | [X] v3.0.0 | Dict[str, Any] | Error dicts | (indirect) | **All 29 memory-related tests pass.** No issues found during audit. --- ## Advanced Memory Tools **Files:** `daem0nmcp/server.py:1756-1914`, `daem0nmcp/server.py:4047-4114`, `daem0nmcp/memory.py:1391-1418`, `daem0nmcp/memory.py:2231-2311`, `daem0nmcp/entity_manager.py` **Test File:** `tests/test_communities.py` (9 tests) ### recall_by_entity **Server Definition:** `daem0nmcp/server.py:4081-4113` **Implementation:** `daem0nmcp/entity_manager.py:159-235` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 4081) - Return type is `Dict[str, Any]` with structured response - Returns error dict for missing project_path - Lazy import of `EntityManager` for module isolation (lines 4103-4106) - [X] **Decorators applied** - VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_communion` - Requires prior `get_briefing()` call - [X] **Implementation Details** - REVIEWED - Searches by entity name OR qualified_name (line 174-177) - Entity type filtering already implemented (line 179-180) - Returns entity metadata plus all referencing memories - Uses `MemoryEntityRef` join table for efficient lookups ### Technical Enhancements (Future) - [ ] **Add entity type filtering** - ALREADY IMPLEMENTED - `entity_type` parameter filters by type (class/function/file) - Applied in WHERE clause when provided - [ ] **Pre-index entity mentions in database** - `MemoryEntityRef` table already provides this index - Entity mentions tracked via `EntityExtractor.extract_all()` - `mention_count` field tracks frequency ### Efficiency Improvements (Low Priority) - [ ] **Batch entity lookup** - Currently single entity per call - Could support `entity_names: List[str]` for bulk queries - Trade-off: API complexity vs. reduced round trips --- ### recall_hierarchical **Server Definition:** `daem0nmcp/server.py:4047-4075` **Implementation:** `daem0nmcp/memory.py:2231-2311` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 4047) - Return type is `Dict[str, Any]` with layered response - Returns error dict for missing project_path - Project path handling correct via `get_project_context()` - [X] **Decorators applied** - VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_communion` - Requires prior `get_briefing()` call - [X] **GraphRAG Implementation** - REVIEWED - Two-layer response: community summaries then individual memories - Community matching via name/summary/tag substring (lines 2276-2283) - Optional `include_members` parameter for drill-down - Falls through to standard `recall()` for individual memories ### Technical Enhancements (Future) - [ ] **Configurable layer depths** - Currently fixed at communities + memories - Could add `layers: List[str]` parameter (e.g., `["communities", "entities", "memories"]`) - Use case: Skip community layer when not needed - [ ] **Semantic community matching** - TODO noted in code (line 2274-2275) - Currently uses substring matching for topic relevance - Could use TF-IDF or vector similarity for better recall - Trade-off: Query complexity vs. relevance quality ### Efficiency Improvements - [ ] **Cache community summaries** - Summaries are static until `rebuild_communities()` called - Could cache community list per project_path - Invalidate on community rebuild - Trade-off: Memory usage vs. repeated community lookups --- ### search_memories **Server Definition:** `daem0nmcp/server.py:1759-1818` **Implementation:** `daem0nmcp/memory.py:2313-2450` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 1759) - Return type is `Union[List[Dict[str, Any]], Dict[str, Any]]` for flexible response - Returns error dict for negative offset (line 1788) - Returns error dict for missing project_path - `include_meta` parameter for pagination metadata (lines 1808-1816) - [X] **Decorators applied** - VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_communion` - Requires prior `get_briefing()` call - [X] **FTS5 Implementation** - REVIEWED - Uses SQLite FTS5 full-text search (line 1795) - BM25 ranking for relevance scoring (line 2362, 2373) - Highlighting already implemented via `snippet()` function (line 2363) - Configurable highlight markers (`highlight_start`, `highlight_end`) - Excerpt token limit configurable (line 2322) ### Technical Enhancements - [ ] **Add highlight snippets in results** - ALREADY IMPLEMENTED - `highlight=True` parameter enables FTS5 snippet extraction - Returns `content_excerpt` field with matched terms highlighted - Configurable excerpt length via `excerpt_tokens` (default 32) ### Efficiency Improvements - [ ] **Use FTS5 virtual table for faster full-text search** - ALREADY IMPLEMENTED - `memories_fts` virtual table created in migrations - BM25 scoring for relevance ranking - Falls back to LIKE search if FTS5 unavailable (line 2327) - [ ] **Index pre-warming on startup** - FTS5 index is cold on first query - Could run dummy query during `init_db()` to warm cache - Trade-off: Startup latency vs. first-query latency --- ### find_related **Server Definition:** `daem0nmcp/server.py:1893-1914` **Implementation:** `daem0nmcp/memory.py:1391-1418` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 1893) - Return type is `List[Dict[str, Any]]` - Returns empty list for non-existent memory_id (line 1408) - Returns error dict for missing project_path - [X] **Decorators applied** - VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_communion` - Requires prior `get_briefing()` call - [X] **Implementation Details** - REVIEWED - Fetches source memory content + rationale (lines 1411-1413) - Uses `search()` with combined text as query (line 1415) - Filters out source memory from results (line 1418) - Limit parameter controls max results ### Technical Enhancements (Future) - [ ] **Configurable relationship type filtering** - Currently semantic similarity only - Could add `relationship_types` parameter to filter by graph edges - Use case: "Find memories that led_to this one" vs. "Find all related" - Could leverage `trace_chain()` internally for graph-based relations - [ ] **Minimum similarity threshold** - Currently returns top N regardless of similarity score - Could add `min_relevance: float` parameter - Trade-off: May return fewer results than requested ### Efficiency Improvements - [ ] **Graph traversal with depth limit** - ALREADY PRESENT IN trace_chain - `find_related` uses semantic search, not graph traversal - For graph-based relations, use `trace_chain()` tool - `max_depth` parameter in `trace_chain()` prevents runaway traversals - [ ] **Cache related memories** - Related memories are deterministic for a given memory_id - Could cache results with invalidation on `remember()` or `link_memories()` - Trade-off: Cache invalidation complexity vs. repeated lookups --- ## Advanced Memory Tools Summary | Tool | FastMCP 3.0 | Return Type | Async | Tests | |------|-------------|-------------|-------|-------| | recall_by_entity | [X] v3.0.0 | Dict[str, Any] | Yes | (indirect) | | recall_hierarchical | [X] v3.0.0 | Dict[str, Any] | Yes | 2 | | search_memories | [X] v3.0.0 | List/Dict | Yes | (covered by memory tests) | | find_related | [X] v3.0.0 | List[Dict] | Yes | (covered by memory tests) | **All 9 community tests pass.** GraphRAG-style hierarchical recall correctly implemented with two-layer response (community summaries + individual memories). --- ## Rules Engine Tools **Files:** `daem0nmcp/server.py:700-887`, `daem0nmcp/rules.py:1-454` **Test File:** `tests/test_rules.py` (19 tests) ### add_rule **Server Definition:** `daem0nmcp/server.py:702-738` **Implementation:** `daem0nmcp/rules.py:91-151` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 702) - Return type is `Dict[str, Any]` with structured response - Returns error dict for missing project_path - Project path handling correct via `get_project_context()` - [X] **Decorators applied** - VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_counsel` - Requires prior `context_check()` call - [X] **Implementation Details** - REVIEWED - Extracts keywords from trigger for backward compatibility (line 115) - Adds document to TF-IDF index immediately (line 135) - Clears rules cache on add to ensure freshness (line 138) - Returns complete rule object with ID and timestamps ### Technical Enhancements (Future) - [ ] **Add rule validation (trigger uniqueness check)** - Currently allows duplicate triggers - Could use `find_similar_rules()` with high threshold to detect near-duplicates - Trade-off: Additional query on every add vs. cleaner rule set - [ ] **Incremental TF-IDF index update** - ALREADY IMPLEMENTED - `add_rule()` calls `index.add_document()` after insert (line 135) - No full rebuild needed for single additions - Index lazy-loaded on first use via `_ensure_index()` --- ### check_rules **Server Definition:** `daem0nmcp/server.py:744-765` **Implementation:** `daem0nmcp/rules.py:153-276` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 744) - Return type is `Dict[str, Any]` with combined guidance - Returns error dict for missing project_path - Project path handling correct via `get_project_context()` - [X] **Decorators applied** - VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_communion` - Requires prior `get_briefing()` call - [X] **TF-IDF Semantic Matching** - VERIFIED - Uses `TFIDFIndex.search()` for semantic matching (line 185) - Configurable threshold (default 0.15) for relevance cutoff - Returns match scores for transparency (lines 238-243) - [X] **Rule Priority Ordering** - VERIFIED - Results sorted by priority (descending), then match score (descending) (lines 208-212) - Higher priority rules appear first in combined guidance - [X] **Test Coverage** - EXCELLENT (7 tests) - `test_check_rules_semantic_match` - TF-IDF matching works - `test_check_rules_no_match` - No false positives - `test_check_rules_multiple_matches` - Guidance combination - `test_check_rules_has_blockers` - Blocker detection - `test_check_rules_returns_match_scores` - Score transparency - `test_semantic_matching_related_concepts` - Related term matching - `test_disabled_rules_not_matched` - Respects enabled flag ### Technical Enhancements (Future) - [ ] **Return matched rule IDs in response** - ALREADY IMPLEMENTED - `rules` field contains list of matched rules with IDs (lines 238-243) - Each rule includes: `id`, `trigger`, `match_score`, `priority` ### Efficiency Improvements - [ ] **Cache rule TF-IDF vectors** - ALREADY IMPLEMENTED - Results cached for 5 seconds via `get_rules_cache()` (lines 174-179) - Cache key includes action and threshold (line 175) - Cache invalidated on rule add/update/delete --- ### list_rules **Server Definition:** `daem0nmcp/server.py:1824-1845` **Implementation:** `daem0nmcp/rules.py:278-308` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 1824) - Return type is `List[Dict[str, Any]]` - Returns error dict for missing project_path - Project path handling correct via `get_project_context()` - [X] **Decorators applied** - VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_communion` - Requires prior `get_briefing()` call - [X] **Implementation Details** - REVIEWED - Ordered by priority (descending), then created_at (descending) (line 285) - `enabled_only` parameter filters disabled rules (line 288) - `limit` parameter for pagination (line 290) ### Technical Enhancements (Future) - [ ] **Add pagination support (offset parameter)** - Currently only `limit` supported - Could add `offset: int = 0` parameter for full pagination - Would enable browsing large rule sets ### Efficiency Improvements - Already lightweight - single SQL query with proper indexes --- ### update_rule **Server Definition:** `daem0nmcp/server.py:1851-1887` **Implementation:** `daem0nmcp/rules.py:310-349` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 1851) - Return type is `Dict[str, Any]` - Returns error dict for non-existent rule (line 328) - Returns error dict for missing project_path - Project path handling correct via `get_project_context()` - [X] **Decorators applied** - VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_counsel` - Requires prior `context_check()` call - [X] **Index Invalidation** - VERIFIED - Invalidates TF-IDF index when `enabled` status changes (lines 341-343) - Uses `_invalidate_index()` which also clears cache (lines 83-89) ### Technical Enhancements (Future) - [ ] **Partial update (only changed fields)** - ALREADY IMPLEMENTED - Each field checked for `is not None` before updating (lines 330-341) - Only provided fields are modified, others preserved ### Efficiency Improvements - [ ] **Invalidate TF-IDF cache entry (not full cache)** - Currently clears entire cache on update (line 89) - Could selectively invalidate entries matching updated rule - Trade-off: Cache key complexity vs. partial invalidation benefit - Recommendation: Leave as-is (cache is small, clears quickly) --- ## Rules Engine Summary | Tool | FastMCP 3.0 | TF-IDF | Caching | Tests | |------|-------------|--------|---------|-------| | add_rule | [X] v3.0.0 | Incremental index | Clears on add | 2 | | check_rules | [X] v3.0.0 | Semantic search | 5s TTL | 7 | | list_rules | [X] v3.0.0 | N/A | N/A | 1 | | update_rule | [X] v3.0.0 | Invalidates index | Clears on update | 1 | **All 19 rules tests pass.** TF-IDF semantic matching correctly implemented with priority ordering and caching. --- ## Covenant Flow Tools **Files:** `daem0nmcp/server.py:1666-2009`, `daem0nmcp/server.py:3002-3060`, `daem0nmcp/memory.py:1131-1260`, `daem0nmcp/memory.py:1762-1885` **Test Files:** `tests/test_covenant_integration.py` (5 tests), `tests/test_covenant_transform.py` (25 tests) ### get_briefing **Server Definition:** `daem0nmcp/server.py:1666-1753` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 1666) - Return type is `Dict[str, Any]` with comprehensive briefing - Returns error dict for missing project_path (line 1681) - No `@requires_communion` decorator (entry point tool - exempt from covenant) - [X] **Sets ctx.briefed = True** - VERIFIED - Line 1721: `ctx.briefed = True` - Marked with comment: "Sacred Covenant: communion complete" - Enables downstream tools protected by `@requires_communion` - [X] **Returns structured briefing with all required fields** - VERIFIED - `statistics` - Memory counts and learning insights (line 1742) - `recent_decisions` - Latest decisions for context (line 1743) - `active_warnings` - Current warnings to observe (line 1744) - `failed_approaches` - Past failures to avoid (line 1745) - `top_rules` - Relevant rules for guidance (line 1746) - `git_changes` - Files changed since last memory (line 1747) - `focus_areas` - Pre-fetched memories for focus topics (line 1748) - `bootstrap` - Auto-bootstrap result on first run (line 1749) - `linked_projects` - Cross-project memory summary (line 1750) - `active_context` - Hot working context items (line 1751) - `message` - Actionable summary message (line 1752) - [X] **Token efficiency (truncation of large fields)** - VERIFIED - Focus areas use `limit=5` per topic (line 1706) - Active context fetched with `condensed=True` (line 1732) - Bootstrap auto-runs only on first call (line 1690-1692) ### Technical Enhancements (Future) - [ ] **Add focus_areas filtering** - ALREADY IMPLEMENTED - `focus_areas: Optional[List[str]]` parameter (line 1670) - Pre-fetches memories for each focus topic via `_prefetch_focus_areas()` (line 1706) ### Efficiency Improvements - [ ] **Truncate long content** - PARTIALLY IMPLEMENTED - Active context uses `condensed=True` - Focus areas pre-fetch with `limit=5` - Consider adding content truncation for very long memory content --- ### context_check **Server Definition:** `daem0nmcp/server.py:1920-2009` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 1920) - Return type is `Dict[str, Any]` with preflight status - Returns error dict for missing project_path (line 1936) - [X] **Decorators applied** - VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_communion` - Requires prior `get_briefing()` call - [X] **Appends to ctx.context_checks with timestamp** - VERIFIED - Lines 1979-1983: Appends dict with `description` and `timestamp` - Marked with comment: "Sacred Covenant: counsel sought" - Enables downstream tools protected by `@requires_counsel` - [X] **Returns preflight token** - VERIFIED - Generates `PreflightToken` via `PreflightToken.issue()` (lines 1989-1993) - Token includes action, session_id, project_path - Serialized token returned in response (line 2004) - 5-minute TTL mentioned in docstring (line 1928) - [X] **Includes relevant memories and rules in response** - VERIFIED - Recalls memories matching description (line 1941) - Checks rules matching description (line 1946) - Combines warnings from both sources (lines 1950-1975) - Returns `memories_found`, `rules_matched` counts (lines 1998-1999) - Returns combined `must_do`, `must_not`, `ask_first` guidance (lines 2001-2003) ### Technical Enhancements (Future) - [ ] **Add description validation** - Currently accepts any string - Could validate minimum length or check for meaningful content - Trade-off: Strictness vs. flexibility ### Efficiency Improvements - [ ] **Combine recall + rules in single DB transaction** - Currently two separate async operations (lines 1941, 1946) - Could batch queries in single session - Trade-off: Code complexity vs. ~1 transaction overhead - Recommendation: Leave as-is (operations are already fast) --- ### record_outcome **Server Definition:** `daem0nmcp/server.py:771-800` **Implementation:** `daem0nmcp/memory.py:1131-1260` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 771) - Return type is `Dict[str, Any]` with updated memory - Returns error dict for non-existent memory (line 1168) - Returns error dict for missing project_path (line 791) - [X] **Decorators applied** - VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_communion` - Requires prior `get_briefing()` call - [X] **Implementation Details** - REVIEWED - Updates memory with `outcome` and `worked` fields (lines 1178-1180) - Creates version record tracking the outcome (lines 1189-1201) - Updates Qdrant metadata with worked status (lines 1204-1217) - Failed outcomes boost memories in future searches (docstring line 1142) ### Technical Enhancements (Future) - [ ] **Auto-link outcome memory to original** - Could create `led_to` relationship from decision to outcome - Enables `trace_chain()` to follow decision consequences - Trade-off: Automatic graph edges vs. explicit user control ### Efficiency Improvements - Already lightweight - single memory update with version tracking --- ### link_memories **Server Definition:** `daem0nmcp/server.py:3002-3031` **Implementation:** `daem0nmcp/memory.py:1762-1867` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 3002) - Return type is `Dict[str, Any]` with link status - Returns error dict for invalid relationship type (line 1786) - Returns error dict for self-reference (line 1791) - Returns error dict for non-existent memories (lines 1801-1803) - Returns error dict for missing project_path (line 3023) - [X] **Decorators applied** - VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_communion` - Requires prior `get_briefing()` call - [X] **Implementation Details** - REVIEWED - Validates relationship type against `VALID_RELATIONSHIPS` (line 1784) - Checks for existing relationship to prevent duplicates (lines 1806-1821) - Creates version records for both source and target (lines 1835-1855) - Supports relationship types: led_to, supersedes, depends_on, conflicts_with, related_to ### Technical Enhancements (Future) - [ ] **Cascade options for relationships** - Currently relationships are independent - Could add `cascade_delete: bool` to auto-remove when memory deleted - Trade-off: Automatic cleanup vs. explicit control ### Efficiency Improvements - [ ] **Batch link operations** - Currently single link per call - Could add `link_memories_batch()` for bulk relationships - Use case: Importing relationships from external sources --- ### unlink_memories **Server Definition:** `daem0nmcp/server.py:3034-3060` **Implementation:** `daem0nmcp/memory.py:1869-1945` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 3034) - Return type is `Dict[str, Any]` with unlink status - Returns error dict for missing project_path (line 3053) - [X] **Decorators applied** - VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_communion` - Requires prior `get_briefing()` call - [X] **Implementation Details** - REVIEWED - Optional `relationship` parameter - removes specific or all relationships - Creates version records tracking relationship removal - Returns count of removed relationships ### Technical Enhancements (Future) - [ ] **Cascade options** (see link_memories above) ### Efficiency Improvements - Already lightweight - single delete query --- ## Covenant Flow Tools Summary | Tool | FastMCP 3.0 | Covenant State | Preflight Token | Tests | |------|-------------|----------------|-----------------|-------| | get_briefing | [X] v3.0.0 | Sets `briefed=True` | N/A | 2 | | context_check | [X] v3.0.0 | Appends to `context_checks` | Issues token | 1 | | record_outcome | [X] v3.0.0 | N/A | N/A | (covered by memory tests) | | link_memories | [X] v3.0.0 | N/A | N/A | (covered by graph tests) | | unlink_memories | [X] v3.0.0 | N/A | N/A | (covered by graph tests) | **All 5 covenant integration tests pass.** Sacred Covenant enforcement working correctly with middleware and decorators. --- ## Code Understanding Tools **Files:** `daem0nmcp/server.py:3472-3612`, `daem0nmcp/code_indexer.py`, `daem0nmcp/entity_manager.py` **Test File:** `tests/test_code_indexer.py` (34 tests) ### index_project **Server Definition:** `daem0nmcp/server.py:3474-3521` **Implementation:** `daem0nmcp/code_indexer.py:694-749` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 3474) - Return type is `Dict[str, Any]` with indexing statistics - Returns error dict when tree-sitter unavailable (lines 3495-3499) - Returns error dict for missing project_path (lines 3501-3502) - [X] **Decorators applied** - VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_communion` - Requires prior `get_briefing()` call - [X] **Implementation Details** - REVIEWED - Multi-language support via tree-sitter-language-pack (Python, TS, JS, Go, Rust, Java, etc.) - Parse tree caching with configurable maxsize (`settings.parse_tree_cache_maxsize`) - Qualified name computation for stable entity IDs across line shifts - Skip directories (node_modules, __pycache__, .venv, etc.) for efficiency ### Technical Enhancements (Future) - [ ] **Incremental indexing (only changed files)** - `index_file_if_changed()` already exists (lines 1084-1130) but not exposed via MCP tool - Uses content hash to skip unchanged files - Could add `incremental: bool = True` parameter to `index_project` - Trade-off: Full reindex guarantee vs. speed for large codebases - [ ] **Run in thread pool to not block event loop** - Tree-sitter parsing is synchronous CPU-bound work - `index_file()` iterates via generator (lines 305-353) - Could wrap with `asyncio.to_thread()` for large files - Trade-off: Complexity vs. responsiveness during large codebase indexing ### Efficiency Improvements - [ ] **Parse tree caching** - ALREADY IMPLEMENTED - `_parse_cache` with content-hash keys (lines 227-253) - Cache stats available via `cache_stats` property - LRU eviction when at capacity - [ ] **Progress reporting for large codebases** - Currently returns final stats only - Could add streaming progress via MCP notifications - Use case: Indexing 10,000+ files with real-time feedback ### Issue Found - **May block on large codebases**: The `index_project()` coroutine runs tree-sitter parsing synchronously within the async function. For very large codebases (thousands of files), this could block the event loop. Consider `asyncio.to_thread()` wrapper for the parsing loop. --- ### find_code **Server Definition:** `daem0nmcp/server.py:3526-3573` **Implementation:** `daem0nmcp/code_indexer.py:877-1000` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 3526) - Return type is `Dict[str, Any]` with search results - Returns error dict when tree-sitter unavailable (lines 3547-3551) - Returns error dict for missing project_path (lines 3553-3554) - [X] **Decorators applied** - VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_communion` - Requires prior `get_briefing()` call - [X] **Implementation Details** - REVIEWED - Semantic search via Qdrant if available (`_semantic_search()`) - Falls back to SQLite text search (`_text_search()`) - Searches name, signature, and docstring fields - Returns entity metadata with relevance scores ### Technical Enhancements (Future) - [ ] **Add language filter** - Currently searches all indexed languages - Could add `language: Optional[str]` parameter (e.g., "python", "typescript") - Would filter by file extension mapping in `LANGUAGE_CONFIG` - [ ] **Add entity type filter** - Could add `entity_type: Optional[str]` parameter (e.g., "class", "function") - Would filter search results to specific entity types ### Efficiency Improvements - [ ] **Use Qdrant for vector similarity** - ALREADY IMPLEMENTED - `_semantic_search()` uses Qdrant when available (lines 952-1000) - Encodes query via `vectors.encode()` - Project path filtering via Qdrant query filter --- ### analyze_impact **Server Definition:** `daem0nmcp/server.py:3578-3612` **Implementation:** `daem0nmcp/code_indexer.py:1002-1083` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 3578) - Return type is `Dict[str, Any]` with impact analysis - Returns error dict when tree-sitter unavailable (lines 3597-3602) - Returns error dict for missing project_path (lines 3604-3605) - [X] **Decorators applied** - VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_communion` - Requires prior `get_briefing()` call - [X] **Implementation Details** - REVIEWED - Finds entity by name (line 1025) - Queries all entities for call/import references (lines 1056-1071) - Returns affected files and entities with location info - Simple implementation - checks `calls` and `imports` lists ### Technical Enhancements (Future) - [ ] **Include call graph depth** - Currently returns direct dependents only - Could add `depth: int = 1` parameter for transitive dependencies - Use case: "What breaks if I change this 2 levels deep?" - [ ] **Source vs. sink analysis** - Add `direction: str = "dependents"` parameter - "dependents" = who calls this (current behavior) - "dependencies" = what this calls (reverse analysis) ### Efficiency Improvements - [ ] **Cache impact analysis results** - Impact analysis is deterministic until reindex - Could cache with invalidation on `index_project()` - Trade-off: Memory usage vs. repeated analysis speed --- ### backfill_entities **Server Definition:** `daem0nmcp/server.py:4156-4208` **Implementation:** `daem0nmcp/entity_manager.py:31-98` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 4156) - Return type is `Dict[str, Any]` with processing stats - Returns error dict for missing project_path (lines 4168-4169) - [X] **Decorators applied** - VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_communion` - Requires prior `get_briefing()` call - [X] **Implementation Details** - REVIEWED - Queries all non-archived memories (lines 4182-4188) - Processes each memory via `EntityManager.process_memory()` (lines 4193-4199) - Extracts entities from content + rationale text - Safe to run multiple times (idempotent entity creation via `_get_or_create_entity`) ### Technical Enhancements (Future) - [ ] **Progress reporting for large memory sets** - Currently processes sequentially with final stats only - Could yield progress via MCP notifications - Use case: Backfilling 1000+ memories with progress bar ### Efficiency Improvements - [ ] **Batch entity extraction** - Currently processes one memory at a time - Could batch memory queries and entity inserts - Trade-off: Transaction size vs. memory usage --- ## Code Understanding Tools Summary | Tool | FastMCP 3.0 | Version Decorator | Async Safe | Tests | |------|-------------|-------------------|------------|-------| | index_project | [X] v3.0.0 | Present | Sync parsing (see note) | 8 | | find_code | [X] v3.0.0 | Present | Yes | 2 | | analyze_impact | [X] v3.0.0 | Present | Yes | 2 | | backfill_entities | [X] v3.0.0 | Present | Yes | (indirect) | **All 34 code indexer tests pass.** Tree-sitter integration working correctly with multi-language support, parse tree caching, and semantic search. --- ## Data Management Tools **Files:** `daem0nmcp/server.py:2743-3347`, `daem0nmcp/memory.py` ### export_data **Server Definition:** `daem0nmcp/server.py:2773-2846` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 2773) - Return type is `Dict[str, Any]` with exported data - Returns error dict for missing project_path (lines 2787-2788) - [X] **Decorators applied** - VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_counsel` - Requires prior `context_check()` call - [X] **Implementation Details** - REVIEWED - Exports all memories and rules in single session (lines 2792-2838) - Optional vector embedding export with base64 encoding (lines 2814-2817) - Includes version and export timestamp metadata (lines 2841-2842) - All timestamps converted to ISO format for portability ### Technical Enhancements (Future) - [ ] **Stream large exports** - Currently loads all memories into memory before returning - Could use async generator for streaming JSON - Use case: Exporting 100,000+ memories without OOM - [ ] **Filter export by date range or category** - Could add `since: Optional[str]`, `categories: Optional[List[str]]` parameters - Enables incremental backups ### Efficiency Improvements - [ ] **Compress output option** - Could add `compress: bool = False` parameter - Use gzip compression for large exports - Trade-off: CPU cost vs. network transfer size --- ### import_data **Server Definition:** `daem0nmcp/server.py:2849-2952` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 2849) - Return type is `Dict[str, Any]` with import stats - Returns error dict for invalid data format (lines 2868-2869) - Returns error dict for missing project_path (lines 2865-2866) - [X] **Decorators applied** - VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_counsel` - Requires prior `context_check()` call - [X] **Implementation Details** - REVIEWED - Validates required `memories` and `rules` keys (line 2868) - Merge mode adds to existing; replace mode clears first (lines 2888-2890) - Datetime parsing handles ISO format with timezone normalization (lines 2873-2882) - Vector embeddings decoded from base64 if present (lines 2895-2900) - File paths normalized during import (lines 2903-2907) ### Technical Enhancements (Future) - [ ] **Dry-run mode** - Could add `dry_run: bool = False` parameter - Validates data structure without committing - Returns what would be imported with any validation errors - [ ] **Conflict resolution options** - Currently merge mode just appends (may create duplicates) - Could add `on_conflict: str = "skip" | "update" | "error"` parameter - Trade-off: Import flexibility vs. data integrity guarantees ### Efficiency Improvements - [ ] **Batch insert with single transaction** - ALREADY IMPLEMENTED - Uses single `async with ctx.db_manager.get_session()` block (line 2887) - All inserts committed atomically on success --- ### rebuild_index **Server Definition:** `daem0nmcp/server.py:2745-2770` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 2745) - Return type is `Dict[str, Any]` with rebuild stats - Returns error dict for missing project_path (lines 2757-2758) - [X] **Decorators applied** - VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_communion` - Requires prior `get_briefing()` call - [X] **Implementation Details** - REVIEWED - Rebuilds both memory and rules TF-IDF indexes (lines 2762-2763) - Returns indexed counts for both (lines 2768-2769) - Lightweight - delegates to `memory_manager.rebuild_index()` and `rules_engine.rebuild_index()` ### Technical Enhancements (Future) - [ ] **Partial rebuild option** - Could add `scope: str = "all" | "memories" | "rules"` parameter - Enables rebuilding only what's needed ### Efficiency Improvements - [ ] **Run in background task** - Could add `async: bool = False` parameter - Returns immediately with task ID for large rebuilds - Poll via separate tool for completion status --- ### pin_memory **Server Definition:** `daem0nmcp/server.py:2957-2995` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 2957) - Return type is `Dict[str, Any]` with pin status - Returns error dict for non-existent memory (line 2985) - Returns error dict for missing project_path (lines 2973-2974) - [X] **Decorators applied** - VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_communion` - Requires prior `get_briefing()` call - [X] **Implementation Details** - REVIEWED - Sets both `pinned` and `is_permanent` flags (lines 2987-2988) - Pinned memories: never pruned, boosted in recall, permanent - Returns truncated content preview (line 2993) ### Technical Enhancements (Future) - [ ] **Bulk pin operation** - Could add `pin_memories_batch(memory_ids: List[int])` tool - Use case: Pinning all memories from a specific file or tag ### Efficiency Improvements - Already lightweight - single memory update --- ### archive_memory **Server Definition:** `daem0nmcp/server.py:3210-3247` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 3210) - Return type is `Dict[str, Any]` with archive status - Returns error dict for non-existent memory (line 3238) - Returns error dict for missing project_path (lines 3226-3227) - [X] **Decorators applied** - VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_communion` - Requires prior `get_briefing()` call - [X] **Implementation Details** - REVIEWED - Sets `archived` flag (line 3240) - Archived memories: hidden from recall but preserved - Returns truncated content preview (line 3245) ### Technical Enhancements (Future) - [ ] **Bulk archive operation** - Could add `archive_memories_batch(memory_ids: List[int])` tool - Use case: Archiving all memories older than N days ### Efficiency Improvements - Already lightweight - single memory update --- ### cleanup_memories **Server Definition:** `daem0nmcp/server.py:3250-3347` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 3250) - Return type is `Dict[str, Any]` with cleanup stats - Returns error dict for missing project_path (lines 3266-3267) - [X] **Decorators applied** - VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_counsel` - Requires prior `context_check()` call - [X] **Implementation Details** - REVIEWED - Groups memories by (category, normalized_content, file_path) (lines 3275-3284) - Finds duplicate groups (>1 memory with same key) (line 3287) - Dry-run mode returns preview with samples (lines 3289-3302) - Merge mode keeps newest, preserves outcomes from any duplicate (lines 3304-3329) - Preserves pinned status across merged duplicates (line 3333) ### Technical Enhancements (Future) - [ ] **Preview mode (dry_run)** - ALREADY IMPLEMENTED - `dry_run: bool = True` parameter (line 3254) - Returns duplicate groups count, total duplicates, and sample previews - Default is dry_run=True for safety ### Efficiency Improvements - [ ] **Index duplicate detection** - Currently loads all memories and groups in Python (lines 3271-3287) - Could use SQL GROUP BY with HAVING COUNT(*) > 1 - Trade-off: Query complexity vs. memory usage for large datasets - Recommendation: Current approach is fine for typical sizes (<100k memories) --- ## Data Management Tools Summary | Tool | FastMCP 3.0 | Version Decorator | Async Safe | Tests | |------|-------------|-------------------|------------|-------| | export_data | [X] v3.0.0 | Present | Yes | (indirect) | | import_data | [X] v3.0.0 | Present | Yes | (indirect) | | rebuild_index | [X] v3.0.0 | Present | Yes | (indirect) | | pin_memory | [X] v3.0.0 | Present | Yes | (indirect) | | archive_memory | [X] v3.0.0 | Present | Yes | (indirect) | | cleanup_memories | [X] v3.0.0 | Present | Yes | (indirect) | **All data management tools are FastMCP 3.0 compliant.** Version decorators present, proper error handling, and async-safe implementations. --- ## Context & Workflow Tools **Files:** `daem0nmcp/server.py:3749-3941`, `daem0nmcp/server.py:3124-3401`, `daem0nmcp/active_context.py` ### get_active_context **Server Definition:** `daem0nmcp/server.py:3793-3817` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 3793) - Return type is `Dict[str, Any]` - Returns error dict for missing project_path (lines 3805-3806) - [X] **Decorators applied** - VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_communion` - Requires prior `get_briefing()` call - **Technical Enhancement:** `condensed` parameter (WIP) - Could add `condensed: bool = False` to strip rationale/context for token efficiency - Already integrated in `get_briefing()` for active context retrieval - **Efficiency:** Eager load memories with context items - Currently fetches context items, then separate query for memory details - Could JOIN to reduce round trips --- ### set_active_context **Server Definition:** `daem0nmcp/server.py:3749-3791` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 3749) - Return type is `Dict[str, Any]` - Returns error dict for missing project_path (lines 3769-3770) - [X] **Decorators applied** - VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_communion` - Requires prior `get_briefing()` call - [X] **Implementation Details** - REVIEWED - Supports optional `expires_in_hours` for auto-expiry (lines 3780-3782) - Priority ordering for display in briefings (line 3755) - Delegates to `ActiveContextManager.add_to_context()` - **Technical Enhancement:** Bulk set - Could add `set_active_context_batch(memory_ids: List[int])` for bulk operations - **Efficiency:** Already lightweight - Single insert per call, no complex queries --- ### remove_from_active_context **Server Definition:** `daem0nmcp/server.py:3819-3845` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 3819) - Return type is `Dict[str, Any]` - Returns error dict for missing project_path (lines 3833-3834) - [X] **Decorators applied** - VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_communion` - Requires prior `get_briefing()` call - **Technical Enhancement:** Bulk remove - Could add `remove_from_active_context_batch(memory_ids: List[int])` - **Efficiency:** Already lightweight - Single DELETE statement per call --- ### clear_active_context **Server Definition:** `daem0nmcp/server.py:3847-3871` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 3847) - Return type is `Dict[str, Any]` - Returns error dict for missing project_path (lines 3859-3860) - [X] **Decorators applied** - VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_communion` - Requires prior `get_briefing()` call - **Technical Enhancement:** Confirm before clear - Could add `confirm: bool = False` parameter for destructive operation safety - Would require `confirm=True` to actually clear - **Efficiency:** Single DELETE statement - Bulk delete all context items for project in one operation --- ### get_memory_versions **Server Definition:** `daem0nmcp/server.py:3878-3905` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 3878) - Return type is `Dict[str, Any]` with `memory_id`, `version_count`, `versions` - Returns error dict for missing project_path (lines 3894-3895) - [X] **Decorators applied** - VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_communion` - Requires prior `get_briefing()` call - **Technical Enhancement:** Diff between versions - Could add `diff: bool = False` parameter to compute deltas between versions - Would show what changed between each version - **Efficiency:** Paginate results - `limit` parameter already present (default 50) - Could add `offset` for full pagination support --- ### get_memory_at_time **Server Definition:** `daem0nmcp/server.py:3907-3941` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 3907) - Return type is `Dict[str, Any]` with historical memory state - Returns error dict for missing project_path (lines 3923-3924) - Returns error dict for invalid timestamp format (lines 3928-3929) - [X] **Decorators applied** - VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_communion` - Requires prior `get_briefing()` call - **Technical Enhancement:** Range query support - Could support `from_timestamp` and `to_timestamp` for querying version ranges - Would return all versions within the time range - **Efficiency:** Index on timestamp - `MemoryVersion.version_at` should be indexed for efficient temporal queries - Currently queries by memory_id first, then filters by time --- ### prune_memories **Server Definition:** `daem0nmcp/server.py:3124-3208` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 3124) - Return type is `Dict[str, Any]` with pruning statistics - Returns error dict for missing project_path (lines 3146-3147) - [X] **Decorators applied** - VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_counsel` - Requires prior `context_check()` call (destructive operation) - [X] **Implementation Details** - REVIEWED - Age-based pruning via `older_than_days` parameter (line 3154) - Access-based protection via `min_recall_count` (line 3165) - Protects: permanent, pinned, with outcomes, frequently accessed (lines 3161-3165) - `dry_run=True` default for safety preview (line 3175) - Rebuilds TF-IDF index after pruning (line 3199) - **Technical Enhancement:** Age-based + access-based pruning - Already implemented with `older_than_days` and `min_recall_count` - Recall count saliency protection ensures valuable memories retained - **Efficiency:** Batch deletion - Deletes all matching memories in single transaction (lines 3195-3196) - Single index rebuild after all deletions --- ### compact_memories **Server Definition:** `daem0nmcp/server.py:3371-3401` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 3371) - Return type is `Dict[str, Any]` with compaction results - Returns error dict for missing project_path (lines 3391-3392) - [X] **Decorators applied** - VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_counsel` - Requires prior `context_check()` call (destructive operation) - [X] **Implementation Details** - REVIEWED - `summary` parameter for user-provided consolidation text (min 50 chars) - `topic` filter for selective compaction (line 3377) - `dry_run=True` default for safety preview - Delegates to `memory_manager.compact_memories()` - **Technical Enhancement:** LLM-based summarization - Currently requires user-provided summary text - Could integrate LLM to auto-generate summaries from memory content - Would require API key configuration - **Efficiency:** Background task for large compaction - Could run large compactions asynchronously with task ID - Would enable progress monitoring for 100+ memory compactions --- ## Context & Workflow Tools Summary | Tool | FastMCP 3.0 | Version Decorator | Async Safe | Tests | |------|-------------|-------------------|------------|-------| | get_active_context | [X] v3.0.0 | Present | Yes | (indirect) | | set_active_context | [X] v3.0.0 | Present | Yes | (indirect) | | remove_from_active_context | [X] v3.0.0 | Present | Yes | (indirect) | | clear_active_context | [X] v3.0.0 | Present | Yes | (indirect) | | get_memory_versions | [X] v3.0.0 | Present | Yes | (indirect) | | get_memory_at_time | [X] v3.0.0 | Present | Yes | (indirect) | | prune_memories | [X] v3.0.0 | Present | Yes | (indirect) | | compact_memories | [X] v3.0.0 | Present | Yes | (indirect) | **All 8 Context & Workflow tools are FastMCP 3.0 compliant.** Version decorators present, proper error handling, and async-safe implementations. --- ## Community & Entity Tools **Files:** `daem0nmcp/server.py:3948-4153`, `daem0nmcp/server.py:3063-3121`, `daem0nmcp/communities.py`, `daem0nmcp/entity_manager.py` ### rebuild_communities **Server Definition:** `daem0nmcp/server.py:3948-3987` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 3948) - Return type is `Dict[str, Any]` with rebuild statistics - Returns error dict for missing project_path (lines 3962-3963) - [X] **Decorators applied** - VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_communion` - Requires prior `get_briefing()` call - [X] **Implementation Details** - REVIEWED - Detects communities via tag co-occurrence (line 3971) - Auto-generates summaries for each community (line 3956) - `min_community_size` parameter for filtering small clusters (line 3952) - Saves communities to database (lines 3977-3980) - **Technical Enhancement:** Incremental community detection - Currently rebuilds all communities from scratch - Could detect only new/changed communities since last rebuild - Would require tracking which memories have changed - **Efficiency:** Background task with progress - Could run asynchronously for large memory sets - Report progress via MCP notifications --- ### list_communities **Server Definition:** `daem0nmcp/server.py:3989-4019` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 3989) - Return type is `Dict[str, Any]` with communities list - Returns error dict for missing project_path (lines 4003-4004) - [X] **Decorators applied** - VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_communion` - Requires prior `get_briefing()` call - **Technical Enhancement:** Filter by level - `level: Optional[int]` parameter already implemented (line 3993) - Filters communities by hierarchy level - **Efficiency:** Already lightweight - Single query to fetch communities with optional level filter --- ### get_community_details **Server Definition:** `daem0nmcp/server.py:4022-4044` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 4022) - Return type is `Dict[str, Any]` with community details and members - Returns error dict for missing project_path (lines 4036-4037) - [X] **Decorators applied** - VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_communion` - Requires prior `get_briefing()` call - **Technical Enhancement:** Include member summaries - Could add `include_summaries: bool = False` parameter - Would return condensed memory content with each member - **Efficiency:** Eager load members - Currently delegates to `CommunityManager.get_community_members()` - Should eagerly load memory details with community query --- ### list_entities **Server Definition:** `daem0nmcp/server.py:4116-4153` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 4116) - Return type is `Dict[str, Any]` with entities list - Returns error dict for missing project_path (lines 4132-4133) - [X] **Decorators applied** - VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_communion` - Requires prior `get_briefing()` call - [X] **Implementation Details** - REVIEWED - Returns most frequently mentioned entities (line 4125) - `entity_type` parameter for filtering (line 4120) - `limit` parameter for pagination (line 4121) - **Technical Enhancement:** Entity type filtering - Already implemented via `entity_type: Optional[str]` parameter - **Efficiency:** Materialized view for counts - Could create materialized view for entity mention counts - Would speed up popularity queries for large datasets --- ### trace_chain **Server Definition:** `daem0nmcp/server.py:3063-3092` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 3063) - Return type is `Dict[str, Any]` with traversal results - Returns error dict for missing project_path (lines 3083-3084) - [X] **Decorators applied** - VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_communion` - Requires prior `get_briefing()` call - [X] **Implementation Details** - REVIEWED - `direction` parameter: forward/backward/both (line 3068) - `relationship_types` filter for specific edge types (line 3069) - `max_depth` parameter prevents runaway traversals (line 3070, default 10) - Delegates to `memory_manager.trace_chain()` - **Technical Enhancement:** Cycle detection - Should detect and handle cycles in memory graph - Prevent infinite loops in cyclic relationships - **Efficiency:** Depth-limited BFS (already present) - `max_depth` parameter limits traversal depth - Prevents expensive full-graph traversals --- ## Community & Entity Tools Summary | Tool | FastMCP 3.0 | Version Decorator | Async Safe | Tests | |------|-------------|-------------------|------------|-------| | rebuild_communities | [X] v3.0.0 | Present | Yes | 2 | | list_communities | [X] v3.0.0 | Present | Yes | 1 | | get_community_details | [X] v3.0.0 | Present | Yes | 1 | | list_entities | [X] v3.0.0 | Present | Yes | (indirect) | | trace_chain | [X] v3.0.0 | Present | Yes | (covered by graph tests) | **All 5 Community & Entity tools are FastMCP 3.0 compliant.** GraphRAG-style community detection working with tag co-occurrence and auto-summarization. --- ## Remaining Tools **Files:** `daem0nmcp/server.py:2516-2739`, `daem0nmcp/server.py:3619-3743`, `daem0nmcp/server.py:4215-4371`, `daem0nmcp/server.py:2171-2263`, `daem0nmcp/server.py:3404-3467` ### ingest_doc **Server Definition:** `daem0nmcp/server.py:2516-2603` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 2516) - Return type is `Dict[str, Any]` with ingestion statistics - Returns error dict for missing project_path (lines 2535-2536) - Returns error dict for invalid chunk_size (lines 2539-2543) - Returns error dict for empty topic (lines 2545-2546) - Returns error dict for URL validation failure (lines 2549-2551) - [X] **Decorators applied** - VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_counsel` - Requires prior `context_check()` call (external content) - [X] **Implementation Details** - REVIEWED - URL validation with SSRF protection (line 2549) - Markdown-aware content chunking (line 2573) - Each chunk stored as a learning memory with source tracking (lines 2583-2592) - Chunk limit protection (MAX_CHUNKS constant) - **Technical Enhancement:** Support more formats (PDF, RSS) - Currently HTML/text only via BeautifulSoup - Could add PDF parsing via PyPDF2 or pdfplumber - Could add RSS/Atom feed parsing - **Efficiency:** Stream large documents - Currently loads full content into memory - Could stream and chunk incrementally for very large documents --- ### propose_refactor **Server Definition:** `daem0nmcp/server.py:2609-2739` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 2609) - Return type is `Dict[str, Any]` with comprehensive analysis - Returns error dict for missing project_path (lines 2624-2625) - Returns error dict for invalid file path (lines 2677-2679) - [X] **Decorators applied** - VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_communion` - Requires prior `get_briefing()` call - [X] **Implementation Details** - REVIEWED - Retrieves file-specific memories (line 2640) - Traces causal chains to understand WHY code evolved (lines 2643-2673) - Scans for TODOs in the file (lines 2681-2687) - Checks relevant rules (lines 2689-2692) - Extracts constraints from warnings and failed approaches (lines 2694-2709) - Identifies opportunities from TODOs (lines 2711-2718) - **Technical Enhancement:** LLM-assisted suggestions - Currently returns raw analysis data - Could integrate LLM to synthesize refactoring recommendations - Would require API key configuration - **Efficiency:** Cache file analysis - Results are deterministic until memories/rules change - Could cache with invalidation on relevant changes --- ### get_graph **Server Definition:** `daem0nmcp/server.py:3095-3121` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 3095) - Return type is `Dict[str, Any]` with graph data - Returns error dict for missing project_path (lines 3113-3114) - [X] **Decorators applied** - VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_communion` - Requires prior `get_briefing()` call - [X] **Implementation Details** - REVIEWED - Supports `memory_ids` or `topic` for node selection (lines 3099-3100) - `format` parameter: "json" or "mermaid" (line 3101) - Delegates to `memory_manager.get_graph()` - **Technical Enhancement:** Filter by relationship type - Could add `relationship_types: Optional[List[str]]` parameter - Would filter edges to specific types (led_to, supersedes, etc.) - **Efficiency:** Lazy load edges - Could return nodes first, edges on demand - Would reduce payload for large graphs --- ### link_projects / unlink_projects / list_linked_projects / consolidate_linked_databases **Server Definitions:** - `link_projects`: lines 3619-3653 - `unlink_projects`: lines 3656-3684 - `list_linked_projects`: lines 3687-3711 - `consolidate_linked_databases`: lines 3714-3742 - [X] **FastMCP 3.0 Compliance** - ALL VERIFIED - All have `@mcp.tool(version="3.0.0")` decorator - All return `Dict[str, Any]` - All have proper error handling for missing project_path - All delegate to `LinkManager` for implementation - [X] **Decorators applied** - ALL VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_communion` - Requires prior `get_briefing()` call - [X] **Implementation Details** - REVIEWED - `link_projects`: Creates bidirectional project links with relationship type (line 3624) - `unlink_projects`: Removes project link (line 3660) - `list_linked_projects`: Returns all links for a project (line 3690) - `consolidate_linked_databases`: Merges memories from linked projects (line 3717) --- ### add_context_trigger / list_context_triggers / remove_context_trigger / check_context_triggers **Server Definitions:** - `add_context_trigger`: lines 4215-4257 - `list_context_triggers`: lines 4260-4296 - `remove_context_trigger`: lines 4299-4329 - `check_context_triggers`: lines 4332-4371 - [X] **FastMCP 3.0 Compliance** - ALL VERIFIED - All have `@mcp.tool(version="3.0.0")` decorator - All return `Dict[str, Any]` - All have proper error handling for missing project_path - All delegate to `ContextTriggerManager` for implementation - [X] **Decorators applied** - ALL VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_communion` - Requires prior `get_briefing()` call - [X] **Implementation Details** - REVIEWED - `add_context_trigger`: Creates auto-recall triggers (file_pattern, tag_match, entity_match) - `list_context_triggers`: Lists configured triggers with optional active filter - `remove_context_trigger`: Removes a trigger by ID - `check_context_triggers`: Matches context against triggers and returns recalled memories --- ### scan_todos **Server Definition:** `daem0nmcp/server.py:2171-2263` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 2171) - Return type is `Dict[str, Any]` with TODO statistics - Returns error dict for missing project_path (lines 2190-2191) - Returns error dict for invalid scan path (lines 2198-2199) - [X] **Decorators applied** - VERIFIED - `@with_request_id` - OpenTelemetry request tracking - `@requires_communion` - Requires prior `get_briefing()` call - [X] **Implementation Details** - REVIEWED - Scans for TODO/FIXME/HACK/XXX/BUG comments (line 2181) - `types` filter for specific TODO types (lines 2206-2208) - `auto_remember` creates warning memories for found items (lines 2232-2245) - Deduplication against existing tech_debt memories (lines 2218-2228) - Groups results by type with summary (lines 2210-2257) - **Efficiency:** Parallel file scanning - Could use `asyncio.gather()` for scanning multiple files - Would speed up large codebase scans --- ### health **Server Definition:** `daem0nmcp/server.py:3404-3467` - [X] **FastMCP 3.0 Compliance** - VERIFIED - `@mcp.tool(version="3.0.0")` decorator present (line 3404) - Return type is `Dict[str, Any]` with health statistics - Returns error dict for missing project_path (lines 3417-3418) - **EXEMPT from covenant** - No `@requires_communion` or `@requires_counsel` - [X] **Decorators applied** - PARTIAL - `@with_request_id` - OpenTelemetry request tracking - **NO covenant decorators** - Intentionally exempt as diagnostic tool - [X] **Implementation Details** - REVIEWED - Returns server version, project path, storage path (lines 3452-3454) - Memory statistics by category (lines 3455-3457) - Rule count (line 3456) - Code entity statistics with index freshness (lines 3462-3466) - Vector store availability (line 3459) - Contexts cached count (line 3458) - **Technical Enhancement:** Include middleware status - Could add `middleware_status` field showing: - CovenantMiddleware enabled/disabled - Recent violation counts - Blocked tool calls (if any) --- ## Remaining Tools Summary | Tool | FastMCP 3.0 | Version Decorator | Covenant | Tests | |------|-------------|-------------------|----------|-------| | ingest_doc | [X] v3.0.0 | Present | counsel | (indirect) | | propose_refactor | [X] v3.0.0 | Present | communion | (indirect) | | get_graph | [X] v3.0.0 | Present | communion | (covered by graph tests) | | link_projects | [X] v3.0.0 | Present | communion | (indirect) | | unlink_projects | [X] v3.0.0 | Present | communion | (indirect) | | list_linked_projects | [X] v3.0.0 | Present | communion | (indirect) | | consolidate_linked_databases | [X] v3.0.0 | Present | communion | (indirect) | | add_context_trigger | [X] v3.0.0 | Present | communion | (indirect) | | list_context_triggers | [X] v3.0.0 | Present | communion | (indirect) | | remove_context_trigger | [X] v3.0.0 | Present | communion | (indirect) | | check_context_triggers | [X] v3.0.0 | Present | communion | (indirect) | | scan_todos | [X] v3.0.0 | Present | communion | (indirect) | | health | [X] v3.0.0 | Present | EXEMPT | (indirect) | **All 13 Remaining tools are FastMCP 3.0 compliant.** The `health` tool is intentionally exempt from covenant enforcement as a diagnostic entry point.