centient 2.25.0 → 2.25.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "centient",
-  "version": "2.25.0",
+  "version": "2.25.1",
   "description": "MCP server for context engineering operations with handoff protocol, health monitoring, session branching with visualization, and query-based artifact loading",
   "type": "module",
   "main": "dist/index.js",
@@ -64,6 +64,7 @@
   },
   "files": [
     "dist",
+    "templates",
     "README.md",
     "CHANGELOG.md"
   ],

package/templates/claude/commands/check-duplicate.md

@@ -0,0 +1,57 @@
+---
+centient-version: 2.25.1
+description: Check for duplicate work
+allowed-tools: mcp__centient__check_duplicate_work
+---
+
+# /check-duplicate
+
+Check if similar work already exists in the current session.
+
+## Usage
+
+```
+/check-duplicate implementing user authentication
+/check-duplicate adding caching to API endpoints
+```
+
+## What This Does
+
+1. Calls `check_duplicate_work` with the description
+2. Returns matches above similarity threshold
+3. Helps avoid redundant implementations
+
+## Workflow
+
+1. **Check for Duplicates**: Call `check_duplicate_work` with:
+   - `description`: Description of the work you want to do
+   - `threshold`: Similarity threshold (default 0.75)
+
+2. **Display Results**: Show any matching prior work:
+   - Similar decisions or implementations
+   - Relevance score
+   - When the similar work was done
+
+3. **Recommend Action**:
+   - If duplicates found: Review existing work first
+   - If no duplicates: Proceed with implementation
+
+## When to Use
+
+Run before starting:
+- New feature implementations
+- Refactoring efforts
+- Bug fixes (might already be fixed)
+- Pattern implementations
+
+## Example Output
+
+```
+Found similar work:
+1. [0.85] Decision: Implemented JWT auth in session 2026-01-10
+   → Consider reusing existing implementation
+
+No action needed - proceed with new work.
+```
+
+Work description: $ARGUMENTS

package/templates/claude/commands/checkpoint.md

@@ -0,0 +1,47 @@
+---
+centient-version: 2.25.1
+description: Save current progress as a checkpoint
+allowed-tools: mcp__centient__*
+---
+
+# /checkpoint
+
+Create a checkpoint of current session progress to preserve context.
+
+## Usage
+
+```
+/checkpoint
+/checkpoint authentication work
+```
+
+## What This Does
+
+1. Reviews current session state via `get_session_summary`
+2. Saves any unsaved decisions or learnings via `save_session_note`
+3. Shows compression metrics via `getCompressionRatio`
+4. Summarizes what was captured
+
+## Workflow
+
+1. **Review Session State**: Call `get_session_summary` to see:
+   - Total notes by type (decisions, hypotheses, blockers, learnings)
+   - Branch visualization if exploration branches exist
+   - Key memories captured so far
+
+2. **Save Recent Work**: If there are unsaved decisions or learnings from recent work, save them via `save_session_note`
+
+3. **Show Metrics**: Call `getCompressionRatio` with current projectPath to show token savings
+
+4. **Summarize**: Display what was captured in this checkpoint
+
+## When to Use
+
+Run `/checkpoint` at these intervals:
+- Every 30-45 minutes during active development
+- After completing a major subtask
+- Before context switching to a different area
+- After making a significant architectural decision
+- When encountering and resolving a blocker
+
+Checkpoint context: $ARGUMENTS

package/templates/claude/commands/constraint.md

@@ -0,0 +1,60 @@
+---
+centient-version: 2.25.1
+description: Manage session constraints
+allowed-tools: mcp__centient__track_constraint, mcp__centient__get_constraints, mcp__centient__lift_constraint, mcp__centient__check_constraint_violation
+---
+
+# /constraint
+
+Track and enforce constraints throughout the session.
+
+## Usage
+
+```
+/constraint add No external API calls during testing
+/constraint list
+/constraint lift <constraint-id>
+/constraint check npm install axios
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `add <constraint>` | Track a new constraint |
+| `list` | Show all active constraints |
+| `lift <id>` | Deactivate a constraint |
+| `check <action>` | Check if action violates constraints |
+
+## Workflow
+
+### Adding Constraints
+
+Call `track_constraint` with:
+- `content`: The constraint text
+- `scope`: "session", "task", or "file"
+- `detected_from`: "explicit" (user-specified)
+
+### Listing Constraints
+
+Call `get_constraints` to see all active constraints with:
+- Constraint ID
+- Content
+- Keywords (auto-extracted)
+- Scope and status
+
+### Checking Violations
+
+Call `check_constraint_violation` with:
+- `proposedAction`: The action to check
+
+Returns violations with severity and reasons.
+
+## Example Constraints
+
+- "No external API calls during data processing"
+- "All database queries must use parameterized statements"
+- "No console.log in production code"
+- "All new functions must have JSDoc comments"
+
+Constraint command: $ARGUMENTS

package/templates/claude/commands/finalize.md

@@ -0,0 +1,56 @@
+---
+centient-version: 2.25.1
+description: End session and create artifacts
+allowed-tools: mcp__centient__*
+---
+
+# /finalize
+
+Crystallize knowledge from this session into permanent, discoverable documentation.
+
+## Usage
+
+```
+/finalize
+/finalize --gist
+```
+
+## What This Does
+
+1. Extracts session memories via `extract_session_memories`
+2. Reviews git changes since session start
+3. Creates finalization pack (JSON + Markdown)
+4. Pushes to Memory Bank via `push_to_memory_bank`
+5. Cleans up session coordination via `finalize_session_coordination`
+6. Commits and pushes to GitHub
+
+## Workflow
+
+1. **Extract Memories**: Call `extract_session_memories` to get all session notes
+
+2. **Review Git Changes**: Check commits and file changes since session start
+
+3. **Generate Artifacts**: Create in `.agent-artifacts/YYYY-MM-DD-<session>/`:
+   - `finalization-pack.json` - Structured knowledge
+   - `finalization-pack.md` - Human-readable narrative
+   - `session-summary.md` - Concise summary
+
+4. **Push to Memory Bank**: Call `push_to_memory_bank` with the finalization pack path
+
+5. **Cleanup**: Call `finalize_session_coordination` to clean up Qdrant session
+
+6. **Commit**: Stage, commit, and push all artifacts to GitHub
+
+## Finalization Pack Structure
+
+The JSON must include:
+- `session`: id, date, branch, commit
+- `summary`: sessionType, title, description, impact
+- `memories`: decisions, learnings, patterns, blockers
+- `files_modified`: created, modified, deleted, read_only
+
+## Options
+
+- `--gist`: Also publish session to GitHub Gist for sharing
+
+Finalize options: $ARGUMENTS

package/templates/claude/commands/history.md

@@ -0,0 +1,60 @@
+---
+centient-version: 2.25.1
+description: Browse session history
+allowed-tools: mcp__centient__searchArtifacts, mcp__centient__loadSession, mcp__centient__diffSessions
+---
+
+# /history
+
+Browse and search session history from finalization packs.
+
+## Usage
+
+```
+/history                        # List recent sessions
+/history authentication         # Search sessions by keyword
+/history load 2026-01-10        # Load specific session
+/history diff 2026-01-09 2026-01-10  # Compare sessions
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| (no args) | List recent sessions |
+| `<keyword>` | Search sessions by keyword |
+| `load <date>` | Load full session context |
+| `diff <date1> <date2>` | Compare two sessions |
+
+## Workflow
+
+### Listing/Searching Sessions
+
+Call `searchArtifacts` with:
+- `keyword`: Search term (optional)
+- `limit`: Max results (default 20)
+
+### Loading a Session
+
+Call `loadSession` with:
+- `project`: Current project name
+- `sessionId`: Session date/ID
+- `includeCode`: true to include code blocks
+
+### Comparing Sessions
+
+Call `diffSessions` with:
+- `project`: Current project name
+- `sessionA`: First session ID
+- `sessionB`: Second session ID
+- `format`: "summary", "detailed", or "json"
+
+## What You'll See
+
+- Session date and title
+- Type (development, bugfix, exploration, etc.)
+- Key decisions and learnings
+- Files modified
+- Patterns identified
+
+History command: $ARGUMENTS

package/templates/claude/commands/note.md

@@ -0,0 +1,50 @@
+---
+centient-version: 2.25.1
+description: Add a note to session memory
+allowed-tools: mcp__centient__save_session_note
+---
+
+# /note
+
+Add a decision, hypothesis, blocker, learning, or finding to session memory.
+
+## Usage
+
+```
+/note decision: Using PostgreSQL over MySQL because...
+/note hypothesis: Caching will reduce latency by 50%
+/note blocker: API rate limiting preventing integration tests
+/note learning: The SDK requires explicit error handling
+/note finding: The bottleneck is in the database query
+```
+
+## Note Types
+
+| Type | When to Use |
+|------|-------------|
+| `decision` | When choosing between alternatives (include rationale) |
+| `hypothesis` | When making an assumption to validate |
+| `blocker` | When encountering an impediment |
+| `learning` | When discovering something valuable |
+| `finding` | When research reveals a fact (can be verified) |
+| `pattern` | When recognizing a reusable approach |
+
+## Workflow
+
+1. Parse the note type from the beginning of the argument
+2. Call `save_session_note` with:
+   - `type`: One of decision, hypothesis, blocker, learning, finding, pattern
+   - `content`: The note content
+   - `metadata`: Include confidence level if applicable
+
+3. Confirm the note was saved
+
+## Best Practices
+
+- **Decisions**: Include alternatives considered and rationale
+- **Hypotheses**: Include validation criteria
+- **Blockers**: Include current status (resolved/unresolved)
+- **Learnings**: Include evidence or source
+- **Findings**: Mark as verified if confirmed by testing
+
+Note to add: $ARGUMENTS

package/templates/claude/commands/patterns.md

@@ -0,0 +1,51 @@
+---
+centient-version: 2.25.1
+description: Search pattern library
+allowed-tools: mcp__centient__findPatterns, mcp__centient__searchPatterns, mcp__centient__loadSkill
+---
+
+# /patterns
+
+Search the pattern library for reusable solutions.
+
+## Usage
+
+```
+/patterns authentication
+/patterns database security
+/patterns --category security
+```
+
+## What This Does
+
+1. Searches pattern library via `findPatterns` (semantic) or `searchPatterns` (keyword)
+2. Displays matching patterns with quality scores
+3. Offers to load full documentation for selected patterns
+
+## Workflow
+
+1. **Search Patterns**: Call `findPatterns` with:
+   - `query`: The search term(s)
+   - `mode`: "fast" for quick results, "comprehensive" for deep search
+   - `category`: Optional category filter
+
+2. **Display Results**: Show patterns with:
+   - Name and category
+   - Quality score (X.X/10)
+   - Brief description
+   - Usage count
+
+3. **Load Details**: If user wants more info, call `loadSkill` with:
+   - `skillId`: Pattern ID (e.g., "security/authentication-jwt")
+   - `includeCode`: true to include implementation
+
+## Categories
+
+- `database` - Database patterns (RLS, migrations, queries)
+- `security` - Security patterns (auth, validation, encryption)
+- `ui` - UI/UX patterns (forms, tables, navigation)
+- `backend` - Backend patterns (APIs, caching, queues)
+- `testing` - Testing patterns (unit, integration, e2e)
+- `architecture` - Architecture patterns (microservices, events)
+
+Search query: $ARGUMENTS

package/templates/claude/commands/promote.md

@@ -0,0 +1,62 @@
+---
+centient-version: 2.25.1
+description: Promote to cross-project knowledge
+allowed-tools: mcp__centient__promote_learning, mcp__centient__promote_decision
+---
+
+# /promote
+
+Promote a learning or decision to cross-project meta-knowledge (Tier 3).
+
+## Usage
+
+```
+/promote learning: Always validate API responses before parsing
+/promote decision: Use structured logging over console.log
+```
+
+## What This Does
+
+1. Parses the type (learning or decision)
+2. Calls the appropriate promote tool
+3. Syncs to Vertex AI Memory Bank if enabled
+4. Confirms promotion with storage location
+
+## Workflow
+
+### For Learnings
+
+Call `promote_learning` with:
+- `title`: Short title for the learning
+- `content`: Full description including context and examples
+- `sourceProject`: Current project name
+- `sourceSession`: Current session ID
+- `tags`: Relevant tags for discovery
+- `verified`: Whether validated through testing
+
+### For Decisions
+
+Call `promote_decision` with:
+- `title`: Short title for the decision
+- `decision`: What was decided
+- `rationale`: Why this decision was made
+- `sourceProject`: Current project name
+- `sourceSession`: Current session ID
+- `tags`: Relevant tags for discovery
+
+## Storage
+
+Promoted knowledge is stored in:
+- `~/.mcp-context/learnings/` - Universal learnings
+- `~/.mcp-context/decisions/` - Universal decisions
+
+If Vertex AI sync is enabled, also pushed to Memory Bank.
+
+## When to Promote
+
+Promote when:
+- A learning applies across multiple projects
+- A decision represents a universal best practice
+- The knowledge would help future you or others
+
+What to promote: $ARGUMENTS

package/templates/claude/commands/recall.md

@@ -0,0 +1,55 @@
+---
+centient-version: 2.25.1
+description: Recall context from memory
+allowed-tools: mcp__centient__session_search, mcp__centient__memory_bank_search
+---
+
+# /recall
+
+Search session memory and Memory Bank for relevant context.
+
+## Usage
+
+```
+/recall authentication decisions
+/recall what did we decide about caching
+/recall --session database      # Current session only
+/recall --history RLS patterns  # Memory Bank only
+```
+
+## What This Does
+
+1. Searches current session memory via `session_search`
+2. Searches persistent Memory Bank via `memory_bank_search`
+3. Returns relevant context with relevance scores
+
+## Workflow
+
+1. **Search Session Memory**: Call `session_search` with:
+   - `query`: The search term
+   - `limit`: Number of results (default 5)
+   - `include_relationships`: true for related notes
+
+2. **Search Memory Bank**: Call `memory_bank_search` with:
+   - `query`: The search term
+   - `projectName`: Current project
+   - `topK`: Number of results
+
+3. **Display Results**: Show context from both sources:
+   - Session memories (ephemeral, current session)
+   - Memory Bank (persistent, cross-session)
+
+## Options
+
+- `--session`: Search only current session memory
+- `--history`: Search only Memory Bank (persistent)
+- Default: Search both
+
+## Best Uses
+
+- "What did we decide about X?"
+- "Have we solved this problem before?"
+- "What patterns apply to X?"
+- "What blockers have we encountered?"
+
+Search query: $ARGUMENTS

package/templates/claude/commands/session-start.md

@@ -0,0 +1,52 @@
+---
+centient-version: 2.25.1
+description: Initialize session memory
+allowed-tools: mcp__centient__*
+---
+
+# /session-start
+
+Initialize a new development session with full context loading.
+
+## Usage
+
+```
+/session-start [optional-feature-keyword]
+/session-start --reference YYYY-MM-DD [feature-keyword]
+```
+
+## What This Does
+
+1. Calls `start_session_coordination` to initialize Qdrant session memory
+2. Optionally seeds session with related memories from Memory Bank
+3. Checks context health via `getContextHealth`
+4. Searches for related past work if keyword provided
+5. Displays session dashboard
+
+## Workflow
+
+1. **Initialize Session**: Call `start_session_coordination` with:
+   - `sessionId`: Format as `YYYY-MM-DD-<keyword>` (e.g., `2026-01-12-auth-flow`)
+   - `projectPath`: Current working directory
+   - `seedTopic`: The keyword argument (if provided)
+
+2. **Check Context Health**: Call `getContextHealth` and display status
+
+3. **Search Related Work** (if keyword provided):
+   - Call `memory_bank_search` with the keyword
+   - Show relevant past memories
+
+4. **Display Dashboard**:
+   ```
+   ═══════════════════════════════════════
+   Session Initialized: <project-name>
+   ═══════════════════════════════════════
+   Session ID: <session-id>
+   Context Health: <status>
+   Memory Bank: <seeded-count> related memories
+   ═══════════════════════════════════════
+   ```
+
+5. **Ask for Focus**: "What are you working on today?"
+
+Session keyword: $ARGUMENTS

package/templates/claude/commands/session-status.md

@@ -0,0 +1,62 @@
+---
+centient-version: 2.25.1
+description: Show current session state
+allowed-tools: mcp__centient__get_session_stats, mcp__centient__get_session_summary, mcp__centient__getContextHealth
+---
+
+# /session-status
+
+Show the current session state and statistics.
+
+## Usage
+
+```
+/session-status
+/session-status --health   # Include context health
+/session-status --tree     # Include branch visualization
+```
+
+## What This Does
+
+1. Calls `get_session_stats` for note counts
+2. Calls `get_session_summary` for comprehensive view
+3. Optionally calls `getContextHealth` for context window status
+
+## Workflow
+
+1. **Get Statistics**: Call `get_session_stats` to see:
+   - Total notes in session
+   - Notes by type (decisions, hypotheses, blockers, etc.)
+
+2. **Get Summary**: Call `get_session_summary` with:
+   - `includeMemories`: true for formatted memories
+   - `includeTree`: true for branch visualization
+
+3. **Check Health** (optional): Call `getContextHealth` to see:
+   - Token usage percentage
+   - Recommendations for optimization
+
+## Display
+
+```
+═══════════════════════════════════════
+Session Status: 2026-01-12-feature
+═══════════════════════════════════════
+
+Notes:
+  Decisions:    3
+  Hypotheses:   2
+  Blockers:     1 (0 resolved)
+  Learnings:    4
+  Patterns:     1
+
+Context Health: GOOD (15% capacity)
+
+Branch Tree:
+  main
+  ├─ feature-a (merged)
+  └─ feature-b (active)
+═══════════════════════════════════════
+```
+
+Status options: $ARGUMENTS