centient 2.20.0

package/README.md

@@ -0,0 +1,433 @@
+# Centient
+
+**Version:** 2.20.0
+**Status:** Production Ready
+**Tools:** 84 across 16 modules
+**Tests:** 1258 passing
+
+Centient is an MCP server that exposes context engineering operations as executable tools, enabling progressive skill loading and achieving **98.7% token reduction** through intelligent context management.
+
+## Key Features
+
+- **Progressive Skill Loading** - Search → Load → Execute pattern for 98.7% token reduction
+- **OpenRouter Integration** - Unified LLM API for 300+ models with consolidated billing
+- **Session Branching** - "What if?" exploration with decision trees and branch visualization
+- **Hallucination Detection** - Claim consistency checking, code feasibility validation, citation verification
+- **Real-time Session Memory** - Qdrant-powered ephemeral coordination with semantic search
+- **Cross-Model Consultation** - Multi-model consensus with Fresh Eyes mode
+- **Semantic Search** - Google File Search for artifact discovery (99.1% token reduction)
+
+## Quick Start
+
+### Option 1: npx (Recommended)
+
+No installation required. Add to your Claude config and restart:
+
+**Claude Code CLI** (`~/.claude.json`):
+
+```json
+{
+  "mcpServers": {
+    "centient": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "centient"]
+    }
+  }
+}
+```
+
+**Claude Desktop** (`~/.config/claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "centient": {
+      "command": "npx",
+      "args": ["-y", "centient"]
+    }
+  }
+}
+```
+
+That's it! Core pattern tools work immediately with zero API keys.
+
+### Option 2: Global Install
+
+```bash
+npm install -g centient
+```
+
+Then use `centient` as the command instead of `npx`.
+
+### Option 3: From Source
+
+```bash
+git clone https://github.com/Szermer/centient.git
+cd centient
+npm install
+npm run build
+```
+
+### Adding API Keys (Optional)
+
+For full functionality, add environment variables to your config:
+
+```json
+{
+  "mcpServers": {
+    "centient": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "centient"],
+      "env": {
+        "QDRANT_URL": "https://your-cluster.cloud.qdrant.io",
+        "QDRANT_API_KEY": "your-qdrant-key",
+        "GEMINI_API_KEY": "your-gemini-key",
+        "OPENROUTER_API_KEY": "your-openrouter-key"
+      }
+    }
+  }
+}
+```
+
+### Environment Variables
+
+| Variable             | Required            | Description                                        |
+| -------------------- | ------------------- | -------------------------------------------------- |
+| `OPENROUTER_API_KEY` | Consultation module | OpenRouter for LLM completions (unified billing)   |
+| `QDRANT_URL`         | Session module      | Qdrant Cloud URL                                   |
+| `QDRANT_API_KEY`     | Session module      | Qdrant API key                                     |
+| `GEMINI_API_KEY`     | Session + Search    | Gemini for embeddings and File Search              |
+
+**API Key Usage:**
+
+- **OpenRouter** - All LLM chat completions (300+ models, consolidated billing)
+- **Gemini** - Embeddings (via `gemini-embedding-001`) and File Search (semantic artifact search)
+
+**Minimal setup:** Core functionality works without API keys. Features degrade gracefully.
+
+## Architecture
+
+### 16 Modules, 84 Tools
+
+| Module                               | Tools | Purpose                                                 |
+| ------------------------------------ | ----- | ------------------------------------------------------- |
+| [Patterns](#patterns-module)         | 13    | Progressive skill loading with versioning               |
+| [Artifacts](#artifacts-module)       | 4     | Historical session knowledge access                     |
+| [Memory](#memory-module)             | 3     | Session runtime context (file-based)                    |
+| [Metrics](#metrics-module)           | 4     | Performance and cost tracking                           |
+| [Search](#search-module)             | 3     | Semantic search via Google File Search                  |
+| [Session](#session-module)           | 19    | Real-time Qdrant coordination + Hallucination Detection |
+| [Stuck](#stuck-module)               | 2     | Stuck detection and recovery                            |
+| [Health](#health-module)             | 4     | System health and service monitoring                    |
+| [Research](#research-module)         | 5     | Research workflow management                            |
+| [Memory Bank](#memory-bank-module)   | 2     | Cross-session persistent memory                         |
+| [Graph](#graph-module)               | 3     | Temporal relationship tracking                          |
+| [Consultation](#consultation-module) | 9     | Cross-model validation                                  |
+| [Branching](#branching-module)       | 6     | Session branching and decision trees                    |
+
+### Patterns Module (13 tools)
+
+Progressive skill loading with **98.7% token reduction**:
+
+- `searchPatterns` - Search by keyword/category (~100-500 tokens)
+- `loadSkill` - Load documentation and interface (~500-1000 tokens)
+- `executeSkill` - Execute with parameters (~50-200 tokens)
+- `findPatterns` - Intelligent search (Qdrant fast / Google FS comprehensive)
+- `trackPatternUsage` - Track usage for auto-promotion
+- `indexPatternLibrary` - Index patterns to vector stores
+- `getPatternVersions` - List versions with changelogs
+- `createPatternVersion` - Create new semver version
+- `deprecatePatternVersion` - Mark version as deprecated
+- `diffPatterns` - Compare two pattern versions visually
+- `recommendPatterns` - Recommend patterns based on session context
+- `predictOutcome` - Predict success probability before execution
+- `signPattern` - Sign pattern with SHA-256 checksums for integrity
+
+### Artifacts Module (4 tools)
+
+Historical session knowledge access:
+
+- `searchArtifacts` - Search finalization packs by keyword
+- `loadSession` - Load session context (with optional query filtering)
+- `getSessionCode` - Extract executable code from sessions
+- `extractSessionContext` - Extract compressed context for handoffs
+
+### Memory Module (3 tools)
+
+File-based session notes:
+
+- `addNote` - Track decisions/hypotheses/blockers
+- `getDecisions` - Retrieve session decisions
+- `getHypotheses` - Retrieve session hypotheses
+
+### Metrics Module (4 tools)
+
+Performance measurement:
+
+- `getCompressionRatio` - Calculate token compression
+- `getPatternReuse` - Track pattern reuse statistics
+- `getCostDashboard` - API cost tracking by service/model
+- `getPatternAnalytics` - Historical usage trends
+
+### Search Module (3 tools)
+
+Semantic search via Google File Search:
+
+- `semanticSearch` - Query artifacts semantically (99.1% token reduction)
+- `indexSession` - Index session to File Search store
+- `getSearchStats` - Get indexing statistics and costs
+
+### Session Module (19 tools)
+
+Real-time coordination via Qdrant + Hallucination Detection:
+
+**Core Coordination:**
+
+- `start_session_coordination` - Initialize Qdrant session memory
+- `save_session_note` - Save decision/hypothesis/blocker/finding
+- `session_search` - Fast semantic search (50-200ms)
+- `check_duplicate_work` - Detect duplicate implementations
+- `get_session_stats` - Get session statistics
+- `get_session_summary` - **NEW:** Comprehensive summary with branch visualization
+- `extract_session_memories` - Extract learnings for finalization
+- `finalize_session_coordination` - Cleanup ephemeral memory
+
+**Constraints:**
+
+- `track_constraint` - Track session constraints
+- `get_constraints` - Get active constraints
+- `lift_constraint` - Deactivate a constraint
+- `check_constraint_violation` - Check for violations
+
+**Approval Tracking:**
+
+- `trackApprovalFingerprint` - Reduce approval fatigue via fingerprints
+
+**Hallucination Detection (6 tools):**
+
+- `flag_for_verification` - Flag low-confidence content
+- `record_verification_outcome` - Record human verification results
+- `check_code_feasibility` - Validate code before execution
+- `check_claim_consistency` - Cross-reference claims
+- `validate_citation` - Verify cited references
+- `get_verification_prompt` - Generate verification steps
+
+### Stuck Module (2 tools)
+
+Stuck detection and recovery:
+
+- `check_stuck_pattern` - Detect repeated blockers, error loops
+- `get_recovery_suggestions` - Generate ranked recovery suggestions
+
+### Health Module (4 tools)
+
+System health and service monitoring:
+
+- `getContextHealth` - Monitor context window health
+- `getQdrantHealth` - Check Qdrant connection status
+- `getCircuitBreakerStats` - Circuit breaker status for external services (Qdrant, OpenAI, Gemini, OpenRouter)
+- `getRateLimitStats` - Rate limit status and token bucket state for all services
+
+### Research Module (5 tools)
+
+Research workflow management:
+
+- `generateResearchPlan` - Create execution plan for review
+- `approveResearchPlan` - Approve/modify/cancel plan
+- `trackResearchProgress` - Track execution status
+- `listResearchSessions` - View all research sessions (inbox pattern)
+- `suggestModelForResearch` - Recommend optimal model by domain
+
+### Memory Bank Module (2 tools)
+
+Cross-session persistent memory via Vertex AI:
+
+- `memory_bank_search` - Semantic search across project memories
+- `memory_bank_list` - List all memories for a project
+
+### Graph Module (3 tools)
+
+Temporal relationship tracking:
+
+- `add_note_relationship` - Link notes with typed relationships
+- `query_temporal_graph` - Traverse causal chains, evolution paths
+- `link_sessions` - Create relationships between sessions
+
+### Consultation Module (9 tools)
+
+Cross-model validation:
+
+- `prepare_consultation_context` - Prepare session context for external LLM
+- `capture_consultation_response` - Parse and persist findings
+- `validate_decision` - Prepare decision validation request
+- `peer_review_session` - Comprehensive session review
+- `peer_review_contract` - Contractor Model with acceptance criteria
+- `validate_review_response` - Validate against contract
+- `seek_consensus` - Multi-model consensus (Fresh Eyes mode)
+- `aggregate_consensus` - Synthesize multi-model responses
+- `consult_llm_stream` - Direct LLM consultation with streaming
+
+### Branching Module (6 tools)
+
+Session branching for "what if?" exploration:
+
+- `mark_decision_point` - Mark where multiple alternatives exist
+- `list_decision_points` - List all decision points with branch counts
+- `create_branch` - Create exploration branch from decision point
+- `list_branches` - View branches with ASCII tree visualization
+- `switch_branch` - Switch active branch context
+- `close_branch` - Close via merge/reject/abandon
+
+**Branch Lifecycle:**
+
+```
+Decision Point → Create Branch → Explore → Close Branch
+                                              ├── merge (adopt insights)
+                                              ├── reject (document why not)
+                                              └── abandon (incomplete)
+```
+
+## Usage Examples
+
+### Progressive Skill Loading (98.7% Token Reduction)
+
+```typescript
+// Step 1: Search for relevant patterns (~100-500 tokens)
+const results = await searchPatterns({
+  category: "database",
+  keyword: "RLS",
+  includeExecutable: true,
+});
+
+// Step 2: Load specific skill (~500-1000 tokens)
+const skill = await loadSkill({
+  skillId: "mcp-integration/rls-policy-generator",
+  includeCode: false,
+});
+
+// Step 3: Execute skill (~50-200 tokens)
+const policy = await executeSkill({
+  skillId: "mcp-integration/rls-policy-generator",
+  input: { table: "profiles", operation: "SELECT" },
+});
+```
+
+**Token savings:** 150K → 2K tokens = **98.7% reduction**
+
+### Session Branching
+
+```typescript
+// Mark a decision point
+await mark_decision_point({
+  description: "Choose authentication approach",
+  category: "architecture",
+  alternatives: ["JWT tokens", "Session cookies", "OAuth2"],
+});
+
+// Create branches to explore alternatives
+await create_branch({
+  decisionPointId: "dp-2025-01-02-001",
+  label: "JWT approach",
+});
+
+// Get session summary with branch visualization
+const summary = await get_session_summary({
+  includeTree: true,
+  includeMemories: true,
+});
+
+// Output includes ASCII tree:
+// Session Branch Tree
+// ═══════════════════════════════════════
+// Main Path ●━━━━━━━━━━━━━━━━━━━━━━━━━━━●
+//               │
+//               ├─ [dp-2025-01-02-001] Choose authentication...
+//               │   ├─ ★ JWT approach
+//               │   └─ ✗ Session cookies (rejected)
+```
+
+### Hallucination Detection
+
+```typescript
+// Check claim consistency before stating as fact
+const consistency = await check_claim_consistency({
+  claim: "We are using JWT with 15-min expiry",
+  projectPath: "/path/to/project",
+  checkAgainst: ["session", "memory_bank", "patterns"],
+});
+
+// Validate code before execution
+const feasibility = await check_code_feasibility({
+  code: 'import { nonExistentPackage } from "fake-lib"',
+  language: "typescript",
+  strictMode: true,
+});
+```
+
+## Development
+
+### Commands
+
+```bash
+npm run build          # Compile TypeScript
+npm run dev            # Development with auto-reload
+npm test               # Run 801 tests
+npm run test:coverage  # With coverage report
+npm run lint           # Type checking
+```
+
+### Project Structure
+
+```
+src/
+├── index.ts              # Entry point (stdio transport)
+├── server.ts             # MCP server config (71 tools)
+├── tools/
+│   ├── patterns/         # Progressive skill loading (9 tools)
+│   ├── artifacts/        # Historical knowledge (4 tools)
+│   ├── memory/           # File-based notes (3 tools)
+│   ├── metrics/          # Performance tracking (4 tools)
+│   ├── search/           # Semantic search (3 tools)
+│   ├── session/          # Qdrant coordination (19 tools)
+│   ├── stuck/            # Stuck detection (2 tools)
+│   ├── health/           # System health (2 tools)
+│   ├── research/         # Research workflow (5 tools)
+│   ├── memory-bank/      # Vertex AI memory (2 tools)
+│   ├── graph/            # Temporal relationships (3 tools)
+│   ├── consultation/     # Cross-model validation (9 tools)
+│   └── branching/        # Session branching (6 tools)
+└── utils/
+    ├── SessionCoordinator.ts   # Qdrant session management
+    ├── ResearchCoordinator.ts  # Research session management
+    └── tokenEstimator.ts       # Token usage tracking
+```
+
+## Documentation
+
+| Document                                                | Description                        |
+| ------------------------------------------------------- | ---------------------------------- |
+| [CLAUDE.md](./CLAUDE.md)                                | Claude Code integration guide      |
+| [MCP_TOOLS_REFERENCE.md](./docs/MCP_TOOLS_REFERENCE.md) | Complete tool reference (71 tools) |
+| [DEVELOPER_GUIDE.md](./docs/DEVELOPER_GUIDE.md)         | Guide for extending the server     |
+| [ARCHITECTURE.md](./docs/ARCHITECTURE.md)               | System architecture and design     |
+| [DESIGN_DECISIONS.md](./docs/DESIGN_DECISIONS.md)       | Technical decision rationale       |
+| [DOCUMENTATION_INDEX.md](./docs/DOCUMENTATION_INDEX.md) | Full documentation navigation      |
+
+## Performance Targets
+
+- **Tool execution:** < 100ms for search operations
+- **Skill execution:** < 50ms overhead vs. direct execution
+- **Session search:** < 200ms semantic search
+- **Token reduction:** ≥98% for progressive loading workflows
+
+## License
+
+MIT
+
+---
+
+**Created:** 2025-11-05
+**Last Updated:** 2025-01-02
+**Maintainer:** Stephen Szermer

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import "./telemetry/tracer.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAIA,OAAO,uBAAuB,CAAC"}

package/dist/index.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+import "./telemetry/tracer.js";
+import { readFileSync, existsSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+function loadEnvFile() {
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    const envPaths = [
+        join(__dirname, "..", ".env"),
+        join(__dirname, "..", "..", ".env"),
+        join(process.cwd(), ".env"),
+    ];
+    for (const envPath of envPaths) {
+        if (existsSync(envPath)) {
+            try {
+                const content = readFileSync(envPath, "utf-8");
+                const lines = content.split("\n");
+                let loaded = 0;
+                for (const line of lines) {
+                    const trimmed = line.trim();
+                    if (!trimmed || trimmed.startsWith("#"))
+                        continue;
+                    const eqIndex = trimmed.indexOf("=");
+                    if (eqIndex === -1)
+                        continue;
+                    const key = trimmed.slice(0, eqIndex).trim();
+                    let value = trimmed.slice(eqIndex + 1).trim();
+                    if ((value.startsWith('"') && value.endsWith('"')) ||
+                        (value.startsWith("'") && value.endsWith("'"))) {
+                        value = value.slice(1, -1);
+                    }
+                    if (!process.env[key]) {
+                        process.env[key] = value;
+                        loaded++;
+                    }
+                }
+                if (loaded > 0) {
+                    console.error(`[MCP Server] Loaded ${loaded} env vars from ${envPath}`);
+                }
+                return;
+            }
+            catch (error) {
+                console.error(`[MCP Server] Failed to load ${envPath}:`, error);
+            }
+        }
+    }
+}
+loadEnvFile();
+const server = createServer();
+const transport = new StdioServerTransport();
+server.connect(transport);
+process.on("SIGINT", () => {
+    console.error("Received SIGINT, shutting down...");
+    process.exit(0);
+});
+process.on("SIGTERM", () => {
+    console.error("Received SIGTERM, shutting down...");
+    process.exit(0);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/server.d.ts

@@ -0,0 +1,4 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+export declare function createServer(): Server;
+export declare function connectServer(server: Server): void;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAyBA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAienE,wBAAgB,YAAY,IAAI,MAAM,CAybrC;AAKD,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAGlD"}