Centient

Version: 3.3.0 Status: Production Ready Tools: 99 across 19 modules

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):

{
  "mcpServers": {
    "centient": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "centient"]
    }
  }
}

Claude Desktop (~/.config/claude/claude_desktop_config.json):

{
  "mcpServers": {
    "centient": {
      "command": "npx",
      "args": ["-y", "centient"]
    }
  }
}

That's it! Core pattern tools work immediately with zero API keys.

Option 2: Global Install

npm install -g centient

Then use centient as the command instead of npx.

Option 3: From Source

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:

{
  "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.

CLI Commands

Centient provides CLI commands for slash command management and diagnostics.

Automatic Global Installation (v3.1.0+)

Slash commands are automatically installed when you install centient:

npm install -g centient
# → Automatically installs 11 slash commands to ~/.claude/commands/
# → Commands are now available in ALL projects

On upgrade, outdated commands are automatically updated while preserving your customizations.

Manual Command Management

# Check global command status
centient setup-global           # Install/update global commands
centient setup-global --force   # Force reinstall all
centient setup-global --remove  # Remove centient commands (preserves custom)

# Project-local commands (optional, overrides global)
centient init                   # Initialize .claude/ directory with commands
centient init --force           # Force overwrite existing files
centient check-commands         # Check status of installed commands
centient update-commands        # Update outdated commands

Command precedence: Project-local (.claude/commands/) overrides global (~/.claude/commands/)

Command Status: | Status | Description | |--------|-------------| | Current | Installed version matches template | | Missing | Template not installed | | Outdated | Installed version lower than template | | Customized | No version header (user modified) |

Global commands installed automatically (in ~/.claude/commands/):

| Command | Description | | ------------------ | ---------------------------------- | | /session-start | Initialize session memory | | /note | Add decision/hypothesis/blocker | | /checkpoint | Save progress checkpoint | | /finalize | End session, create artifacts | | /promote | Promote to cross-project knowledge | | /patterns | Search pattern library | | /recall | Recall from memory | | /check-duplicate | Detect duplicate work | | /constraint | Manage constraints | | /history | Browse session history | | /session-status | Show session state |

Optional project-local structure (via centient init):

.claude/
├── commands/           # Project-specific command overrides
├── hooks/              # Git hooks (if templates exist)
└── settings.json       # Project settings

Diagnostics

# Show version
centient --version

# Show help
centient --help

# List all 98 MCP tools
centient --list-tools

# Run health check (validates API connections)
centient --health

# Show configuration (env vars, paths)
centient --config

# Show usage statistics from audit log
centient --stats

# Monitor audit log activity
centient --monitor              # Last 20 events
centient --monitor --last 50    # Last 50 events
centient --monitor --follow     # Live tail mode

Architecture

19 Modules, 99 Tools

| Module | Tools | Purpose | | ------------------------------------ | ----- | ------------------------------------------------------- | | Patterns | 13 | Progressive skill loading with versioning | | Artifacts | 5 | Historical session knowledge access | | Memory | 3 | Session runtime context (file-based) | | Metrics | 5 | Performance and cost tracking | | Search | 3 | Semantic search via Google File Search | | Session | 20 | Real-time Qdrant coordination + Hallucination Detection | | Stuck | 2 | Stuck detection and recovery | | Health | 4 | System health and service monitoring | | Research | 5 | Research workflow management | | Memory Bank | 2 | Cross-session persistent memory | | Graph | 3 | Temporal relationship tracking | | Consultation | 9 | Cross-model validation | | Branching | 6 | Session branching and decision trees | | Knowledge | 3 | Cross-project meta-knowledge | | Trails | 8 | DevLex syntopic trail discovery | | Channels | 5 | Channel-based agent communication | | RLVR | 1 | Reinforcement learning verification |

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 (5 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
• diffSessions - Compare two sessions side-by-side

Memory Module (3 tools)

File-based session notes:

• addNote - Track decisions/hypotheses/blockers
• getDecisions - Retrieve session decisions
• getHypotheses - Retrieve session hypotheses

Metrics Module (5 tools)

Performance measurement:

• getCompressionRatio - Calculate token compression
• getPatternReuse - Track pattern reuse statistics
• getCostDashboard - API cost tracking by service/model
• getPatternAnalytics - Historical usage trends
• getAuditLog - Query audit log for pattern/skill access history

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 (20 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)
• ask_session - Natural language queries against session memory
• check_duplicate_work - Detect duplicate implementations
• get_session_stats - Get session statistics
• get_session_summary - 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)

Knowledge Module (3 tools)

Cross-project meta-knowledge for Tier 3 universal learnings:

• promote_learning - Promote insights to ~/.centient/knowledge/learnings/
• promote_decision - Promote decisions to ~/.centient/knowledge/decisions/
• search_meta_knowledge - Search cross-project knowledge

Trails Module (8 tools)

DevLex syntopic trail discovery for knowledge exploration:

• trail_query_topics - Browse topic hierarchy (domains/subdomains)
• trail_query_by_topic - Find articles by topic
• trail_query_intersect - Find topic overlaps
• trail_discover_convergence - Find converging insights from independent sources
• trail_discover_influence - Trace influence chains through knowledge
• trail_discover_auto - Auto-discover trails based on patterns
• trail_list - List existing trails
• trail_view - View trail details

Channels Module (5 tools)

Channel-based agent communication for multi-agent coordination:

• channel_create - Create a new channel for agent communication
• channel_message - Post message with threading, @mentions, task linking
• channel_read - Read messages with filtering (unread, mentions, time)
• channel_list - List all channels with optional unread counts
• channel_delete - Delete a channel and all its messages

RLVR Module (1 tool)

Reinforcement learning verification:

• run_rlvr_task - Execute RLVR verification tasks

Usage Examples

Progressive Skill Loading (98.7% Token Reduction)

// 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

// 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

// 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

npm run build          # Compile TypeScript
npm run dev            # Development with auto-reload
npm test               # Run all 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 (100 tools)
├── tools/
│   ├── patterns/         # Progressive skill loading (13 tools)
│   ├── artifacts/        # Historical knowledge (5 tools)
│   ├── memory/           # File-based notes (3 tools)
│   ├── metrics/          # Performance tracking (5 tools)
│   ├── search/           # Semantic search (3 tools)
│   ├── session/          # Qdrant coordination (21 tools)
│   ├── stuck/            # Stuck detection (2 tools)
│   ├── health/           # System health (4 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)
│   ├── knowledge/        # Cross-project meta-knowledge (3 tools)
│   ├── trails/           # DevLex syntopic discovery (8 tools)
│   ├── channels/         # Agent communication (5 tools)
│   └── rlvr/             # RLVR verification (1 tool)
└── utils/
    ├── SessionCoordinator.ts   # Qdrant session management
    ├── ResearchCoordinator.ts  # Research session management
    ├── MetaKnowledgeManager.ts # Cross-project meta-knowledge
    ├── ChannelCoordinator.ts   # Agent communication channels
    └── tokenEstimator.ts       # Token usage tracking

Documentation

| Document | Description | | ------------------------------------------------------- | ---------------------------------- | | CLAUDE.md | Claude Code integration guide | | MCP_TOOLS_REFERENCE.md | Complete tool reference (93 tools) | | DEVELOPER_GUIDE.md | Guide for extending the server | | ARCHITECTURE.md | System architecture and design | | DESIGN_DECISIONS.md | Technical decision rationale | | 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: 2026-01-12 Maintainer: Stephen Szermer