---
name: 'Knowledge Graph Validation'
description: 'Validates knowledge graph manager, state reinforcement, conversation memory, graph persistence, and session cleanup'
on:
  pull_request:
    paths:
      - 'src/utils/knowledge-graph-manager.ts'
      - 'src/utils/state-reinforcement-manager.ts'
      - 'src/utils/conversation-memory-manager.ts'
      - 'tests/utils/knowledge-graph*.test.ts'
  push:
    branches:
      - main
  workflow_dispatch:
permissions:
  issues: read
  pull-requests: read
safe-outputs:
  create-issue:
    title-prefix: '[knowledge-graph]'
  add-comment:
tools:
  bash: true
  github:
    toolsets: [issues, pull_requests]
network:
  allowed:
    - defaults
    - node
---

# Knowledge Graph Validation

You validate the knowledge graph, state reinforcement, and conversation memory subsystems of the MCP server.

## Context

The mcp-adr-analysis-server maintains persistent state through three interconnected systems:

1. **Knowledge Graph Manager** (`src/utils/knowledge-graph-manager.ts`)
   - Tracks intents, tool executions, ADR decisions, and relationships
   - Persists to OS temp directory: `$TMPDIR/{projectName}/cache/knowledge-graph-snapshots.json`
   - Provides `queryKnowledgeGraph()` for semantic context retrieval
   - Memory operations limited to last 1000 entries

2. **State Reinforcement Manager** (`src/utils/state-reinforcement-manager.ts`)
   - Context decay mitigation: re-injects core context every 5 turns or when responses exceed 3000 tokens
   - Integrates recent knowledge graph intents into context reminders

3. **Conversation Memory Manager** (`src/utils/conversation-memory-manager.ts`)
   - Structured external memory for long conversations
   - Stores sessions, expandable content, and resumption context
   - Auto-cleanup of sessions older than 24 hours

## Validation Steps

### Step 0: Install Dependencies

Install build tools required for native module compilation (e.g., tree-sitter), then install npm dependencies with error-tolerant fallbacks.

```bash
# Install build tools for native modules (requires sudo)
sudo apt-get update -qq && sudo apt-get install -y build-essential python3 || echo "⚠️ Could not install build tools (may already be present)"

# Install npm dependencies with fallback
if ! npm ci; then
  echo "⚠️ npm ci failed, falling back to npm install..."
  npm install
fi

# Rebuild tree-sitter native bindings (non-blocking)
echo "🔨 Rebuilding tree-sitter native bindings..."
if ! npm rebuild tree-sitter; then
  echo "⚠️ Tree-sitter rebuild failed, but continuing (tests handle graceful fallback)"
fi
```

If `npm` is not available or both install commands fail, you can still run the persistence validation steps (Steps 4 and 5) using `node` with pre-built `dist/` if available.

### Step 1: Knowledge Graph Manager Tests

```bash
npm test -- tests/utils/knowledge-graph-manager.test.ts --verbose --coverage
```

Verify all tests pass and coverage meets the 85% threshold.

### Step 2: State Reinforcement Tests

```bash
npm test -- tests/utils/state-reinforcement-manager.test.ts --verbose
```

### Step 3: Conversation Memory Tests

```bash
npm test -- tests/utils/conversation-memory-manager.test.ts --verbose
```

### Step 4: Graph Persistence Validation

Run an end-to-end persistence test:

```bash
node -e "
  import { KnowledgeGraphManager } from './dist/src/utils/knowledge-graph-manager.js';
  import fs from 'fs';
  import os from 'os';
  import path from 'path';

  const testProject = 'kg-validation-test';
  const kg = new KnowledgeGraphManager(testProject);

  // Add test data
  kg.addIntent('test-intent', 'Test validation intent');
  kg.addToolExecution('test-tool', { param: 'test' });
  kg.addADRDecision('ADR-001', 'Test ADR', 'Test decision');

  // Query graph
  const results = kg.queryKnowledgeGraph('test');
  if (results.length === 0) {
    console.error('Knowledge graph query failed');
    process.exit(1);
  }

  // Verify persistence
  const cacheDir = path.join(os.tmpdir(), testProject, 'cache');
  const snapshotFile = path.join(cacheDir, 'knowledge-graph-snapshots.json');

  if (!fs.existsSync(snapshotFile)) {
    console.error('Knowledge graph snapshot not persisted');
    process.exit(1);
  }

  console.log('Knowledge graph persistence validated');
  console.log('Query system operational');

  // Cleanup
  fs.rmSync(cacheDir, { recursive: true, force: true });
"
```

### Step 5: Memory Cleanup Validation

Test that old sessions are properly cleaned up:

```bash
node -e "
  import { ConversationMemoryManager } from './dist/src/utils/conversation-memory-manager.js';
  import fs from 'fs';
  import os from 'os';
  import path from 'path';

  const testProject = 'memory-cleanup-test';
  const memory = new ConversationMemoryManager(testProject);

  // Create test session
  const sessionId = memory.createSession('test-context');
  memory.addMessage(sessionId, 'user', 'test message', {});

  // Verify cleanup of old sessions
  memory.cleanupOldSessions();

  console.log('Memory cleanup validated');

  // Cleanup test data
  const memoryDir = path.join(os.tmpdir(), testProject, 'conversation-memory');
  if (fs.existsSync(memoryDir)) {
    fs.rmSync(memoryDir, { recursive: true, force: true });
  }
"
```

## On Failure

If any step fails:

1. **For PR events**: Add a comment to the PR identifying which subsystem failed (knowledge graph, state reinforcement, or conversation memory) and the specific test failures.

2. **For push/dispatch events**: Create an issue:

**Title**: `[knowledge-graph] {subsystem}: {failure description}`

**Body**:

```markdown
## Knowledge Graph Validation Failure

**Subsystem**: {Knowledge Graph / State Reinforcement / Conversation Memory}
**Trigger**: {PR/push/dispatch}

### Failure Details

{full error output from the failing step}

### Components Tested

| Component               | Status      |
| ----------------------- | ----------- |
| Knowledge Graph Manager | {pass/fail} |
| State Reinforcement     | {pass/fail} |
| Conversation Memory     | {pass/fail} |
| Graph Persistence       | {pass/fail} |
| Memory Cleanup          | {pass/fail} |

### Impact Assessment

{what functionality is affected by this failure}

### Recommended Fix

1. {step 1}
2. {step 2}

---

_Generated by Knowledge Graph Validation agentic workflow_
```

## On Success

- **For PR events**: Add a comment confirming all knowledge graph and memory validations passed
- **For push/dispatch events**: No issue needed

---

_Replaces: .github/agents/knowledge-graph-validation.yml_
