π The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
Coherence Engine Integration Points
Overview
This document describes how the Coherence Engine domain integrates with Claude Flow V3 modules, including the Memory, Security, Coordination, and Hive-Mind domains.
Integration Architecture
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Claude Flow V3 β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β β
β βββββββββββββββββββ βββββββββββββββββββ βββββββββββββββββββ ββββββββββββββ β
β β Memory Domain β β Security Domain β β Coordination β β Hive-Mind β β
β β β β β β Domain β β Domain β β
β ββββββββββ¬βββββββββ ββββββββββ¬βββββββββ ββββββββββ¬βββββββββ βββββββ¬βββββββ β
β β β β β β
β β β β β β
β ββββββββββΌβββββββββββββββββββββΌβββββββββββββββββββββΌβββββββββββββββββββΌβββββββ β
β β Coherence Engine Plugin β β
β β ββββββββββββββββ ββββββββββββββββ ββββββββββββββββ ββββββββββββββββ β β
β β β Coherence β β Input β β Consensus β β Swarm β β β
β β β Gate β β Validator β β Verifier β β Analyzer β β β
β β ββββββββββββββββ ββββββββββββββββ ββββββββββββββββ ββββββββββββββββ β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Memory Domain Integration
Integration Type: Shared Kernel
The Coherence Engine shares a kernel with the Memory domain for pre-storage validation.
Hook: pre-memory-store
Purpose: Validate memory entries for contradiction before storage.
Trigger: Called before any entry is stored in memory.
Implementation:
// Hook registration
{
name: 'pr/pre-memory-store',
event: 'pre-memory-store',
priority: HookPriority.HIGH,
handler: async (context, payload) => {
const gate = context.get<CoherenceGate>('pr.coherenceGate');
const memoryService = context.get('memory');
// Get existing context from same namespace
const existingEntries = await memoryService.search({
namespace: payload.namespace,
limit: 10,
embedding: payload.embedding
});
const validation = await gate.validate(payload, existingEntries);
if (validation.action === 'reject') {
throw new CoherenceViolationError(
validation.coherenceResult.energy,
validation.coherenceResult.violations
);
}
// Add coherence metadata
if (validation.action === 'warn') {
payload.metadata = {
...payload.metadata,
coherenceWarning: true,
coherenceEnergy: validation.coherenceResult.energy
};
}
return payload;
}
}
Extended Service: CoherentMemoryService
Purpose: Provides memory operations with built-in coherence validation.
Methods:
| Method | Description | Coherence Integration |
|---|---|---|
storeWithCoherence() |
Store with validation | Pre-store coherence check |
searchCoherent() |
Search with filtering | Post-search coherence filter |
validateNamespace() |
Validate namespace | Batch coherence analysis |
Usage Example:
// Initialize coherent memory service
const coherentMemory = new CoherentMemoryService(memoryService, coherenceGate);
// Store with coherence validation
const result = await coherentMemory.storeWithCoherence({
namespace: 'agents/decisions',
key: 'decision-123',
content: 'Agent decided to proceed with option A',
embedding: embeddingVector
});
if (!result.stored) {
console.warn(`Entry rejected: energy=${result.coherenceResult.energy}`);
}
// Search with coherence filtering
const coherentResults = await coherentMemory.searchCoherent(
queryEmbedding,
10,
{ namespace: 'agents/decisions', minCoherence: 0.8 }
);
Memory Namespaces Used
| Namespace | Purpose |
|---|---|
pr/coherence-checks |
Stores coherence check history |
pr/stability-metrics |
Stores stability analysis results |
pr/thresholds |
Stores configured thresholds |
Security Domain Integration
Integration Type: Conformist
The Coherence Engine conforms to the Security domain's patterns for input validation.
Hook: pre-rag-retrieval
Purpose: Prevent hallucinations by validating retrieved context coherence.
Trigger: Called before RAG retrieval results are used.
Implementation:
{
name: 'pr/pre-rag-retrieval',
event: 'pre-rag-retrieval',
priority: HookPriority.HIGH,
handler: async (context, payload) => {
const bridge = context.get<PrimeRadiantBridge>('pr.bridge');
const vectors = payload.retrievedDocs.map(d => new Float32Array(d.embedding));
if (vectors.length < 2) return payload;
const coherence = await bridge.checkCoherence(vectors);
if (coherence.energy > 0.5) {
// Filter contradictory documents
console.warn(`RAG coherence warning: ${coherence.violations.join(', ')}`);
return {
...payload,
retrievedDocs: filterMostCoherent(payload.retrievedDocs, vectors),
coherenceFiltered: true,
originalCoherenceEnergy: coherence.energy
};
}
return payload;
}
}
AIDefence Integration
Purpose: Extend threat detection with coherence-based analysis.
Integration Points:
| AIDefence Feature | Coherence Enhancement |
|---|---|
| Input validation | Coherence-based content validation |
| Threat detection | Causal analysis of attack patterns |
| Pattern matching | Spectral analysis of threat signatures |
Usage Example:
// Extend AIDefence with coherence checking
const enhancedScan = async (input: string, embedding: Float32Array) => {
// Standard AIDefence scan
const aidefenceResult = await aidefence.scan(input);
// Coherence enhancement
const coherenceResult = await coherenceGate.validate(
{ embedding },
await getRecentInputEmbeddings()
);
return {
...aidefenceResult,
coherenceScore: coherenceResult.coherenceResult.confidence,
coherenceWarnings: coherenceResult.coherenceResult.violations
};
};
Coordination Domain Integration
Integration Type: Shared Kernel
The Coherence Engine shares a kernel with Coordination for swarm stability analysis.
Hook: post-swarm-task
Purpose: Analyze swarm stability after task completion.
Trigger: Called after a swarm task completes.
Implementation:
{
name: 'pr/post-swarm-task',
event: 'post-task',
priority: HookPriority.NORMAL,
handler: async (context, payload) => {
if (!payload.isSwarmTask) return payload;
const bridge = context.get<PrimeRadiantBridge>('pr.bridge');
const coordination = context.get('coordination');
// Get agent communication patterns
const agentStates = await coordination.getAgentStates();
const adj = buildCommunicationMatrix(agentStates);
// Analyze spectral stability
const spectral = await bridge.analyzeSpectral(adj);
// Store metrics
await context.get('memory').store({
namespace: 'pr/stability-metrics',
key: `task-${payload.taskId}`,
content: JSON.stringify({
stable: spectral.stable,
spectralGap: spectral.spectralGap,
timestamp: Date.now()
})
});
return {
...payload,
stabilityMetrics: spectral
};
}
}
Swarm Health Monitoring
MCP Tool: pr/swarm-health
Purpose: Continuous swarm health monitoring using spectral analysis.
Metrics Provided:
| Metric | Description | Healthy Range |
|---|---|---|
spectralGap |
Gap between top eigenvalues | > 0.1 |
stabilityIndex |
Aggregate stability measure | > 0.5 |
clusteringCoefficient |
Agent clustering tendency | 0.3 - 0.7 |
connectivityScore |
Overall swarm connectivity | > 0.8 |
Usage Example:
// Monitor swarm health
const health = await primeRadiantPlugin.tools.swarmHealth({
swarmId: 'main-swarm',
includeHistory: true
});
if (!health.stable) {
console.warn('Swarm instability detected:', health.recommendations);
}
Hive-Mind Domain Integration
Integration Type: Shared Kernel
The Coherence Engine shares a kernel with Hive-Mind for consensus verification.
Hook: pre-consensus
Purpose: Mathematically validate consensus proposals before voting.
Trigger: Called before a consensus vote is accepted.
Implementation:
{
name: 'pr/pre-consensus',
event: 'pre-consensus',
priority: HookPriority.HIGH,
handler: async (context, payload) => {
const bridge = context.get<PrimeRadiantBridge>('pr.bridge');
// Check proposal coherence against existing decisions
const vectors = [
new Float32Array(payload.proposalEmbedding),
...payload.existingDecisions.map(d => new Float32Array(d.embedding))
];
const coherence = await bridge.checkCoherence(vectors);
if (coherence.energy > 0.7) {
return {
...payload,
rejected: true,
rejectionReason: `Proposal contradicts existing decisions (energy: ${coherence.energy.toFixed(3)})`
};
}
return {
...payload,
coherenceEnergy: coherence.energy,
coherenceConfidence: coherence.confidence
};
}
}
Extended Service: CoherentHiveMind
Purpose: Provides hive-mind operations with mathematical verification.
Methods:
| Method | Description | Coherence Integration |
|---|---|---|
verifyConsensus() |
Verify consensus mathematically | Coherence + spectral check |
analyzeSwarmHealth() |
Analyze swarm health | Spectral stability analysis |
proposeWithValidation() |
Propose with pre-validation | Pre-proposal coherence gate |
Usage Example:
// Initialize coherent hive-mind
const coherentHive = new CoherentHiveMind(hiveMind, primeRadiantBridge);
// Verify consensus mathematically
const verification = await coherentHive.verifyConsensus('proposal-123');
if (!verification.verified) {
console.warn('Consensus not verified:', {
coherenceEnergy: verification.coherenceEnergy.getValue(),
spectralStability: verification.spectralStability,
agreementRatio: verification.agreementRatio
});
}
// Analyze swarm health
const health = await coherentHive.analyzeSwarmHealth();
if (!health.healthy) {
for (const rec of health.recommendations) {
console.warn('Health recommendation:', rec);
}
}
Byzantine Fault Tolerance Enhancement
Purpose: Enhance BFT with mathematical coherence checking.
Integration:
// BFT with coherence verification
async function bftWithCoherence<T>(
operation: () => Promise<T>,
replicaCount: number = 3
): Promise<T> {
const results: T[] = [];
const embeddings: Float32Array[] = [];
// Execute on replicas
for (let i = 0; i < replicaCount; i++) {
const result = await operation();
results.push(result);
embeddings.push(await embed(result));
}
// Check coherence of results
const coherence = await bridge.checkCoherence(embeddings);
if (coherence.energy > 0.5) {
throw new Error('BFT results are incoherent - potential Byzantine failure');
}
// Return majority result
return selectMajority(results);
}
Embeddings Domain Integration
Integration Type: Customer-Supplier
The Coherence Engine is a customer of the Embeddings domain.
Embedding Generation
Purpose: Generate embeddings for coherence checking.
Integration:
// Use embeddings service for coherence input
const embeddingsService = context.get<EmbeddingsService>('embeddings');
async function prepareForCoherence(content: string): Promise<Float32Array> {
const embedding = await embeddingsService.generate(content);
return new Float32Array(embedding);
}
// Batch embedding for multiple entries
async function prepareMultiple(contents: string[]): Promise<Float32Array[]> {
const embeddings = await embeddingsService.batchGenerate(contents);
return embeddings.map(e => new Float32Array(e));
}
Hyperbolic Embedding Support
Purpose: Enhanced coherence checking with hyperbolic embeddings.
Integration:
// Use hyperbolic embeddings for hierarchical coherence
const hyperbolicEmbedding = await embeddingsService.generate(content, {
hyperbolic: true,
curvature: -1
});
// Coherence in Poincare ball
const coherence = await bridge.checkCoherenceHyperbolic(
hyperbolicEmbeddings,
{ curvature: -1 }
);
MCP Tool Registration
Tools Provided
| Tool Name | Category | Description |
|---|---|---|
pr/coherence-check |
Coherence | Check vector coherence |
pr/spectral-analyze |
Spectral | Analyze spectral stability |
pr/causal-infer |
Causal | Do-calculus inference |
pr/consensus-verify |
Consensus | Verify multi-agent consensus |
pr/quantum-topology |
Topology | Compute topological features |
pr/memory-gate |
Memory | Pre-storage coherence gate |
Tool Registration Example
// Register tools with MCP server
mcpServer.registerTools([
{
name: 'pr_coherence_check',
description: 'Check coherence using Sheaf Laplacian',
inputSchema: {
type: 'object',
properties: {
vectors: { type: 'array', items: { type: 'array', items: { type: 'number' } } },
threshold: { type: 'number', default: 0.3 }
},
required: ['vectors']
},
handler: coherenceCheckHandler
},
// ... other tools
]);
Event Integration
Domain Events Emitted
| Event | Trigger | Consumers |
|---|---|---|
CoherenceViolationDetected |
Entry fails coherence | Memory, Logging |
StabilityThresholdBreached |
Spectral gap too low | Coordination, Alerting |
ConsensusVerificationFailed |
Consensus not verified | Hive-Mind, Logging |
Event Handling Example
// Subscribe to coherence events
eventBus.subscribe('CoherenceViolationDetected', async (event) => {
// Log violation
await logger.warn('Coherence violation', {
energy: event.energy,
violations: event.violations,
namespace: event.namespace
});
// Update metrics
await metrics.increment('coherence.violations', {
namespace: event.namespace,
action: event.action
});
});
// Subscribe to stability events
eventBus.subscribe('StabilityThresholdBreached', async (event) => {
// Alert on critical instability
if (event.spectralGap < 0.05) {
await alerting.critical('Swarm stability critical', {
sourceType: event.sourceType,
sourceId: event.sourceId,
recommendations: event.recommendations
});
}
});
Performance Considerations
Caching Strategy
// LRU cache for coherence results
const coherenceCache = new LRUCache<string, CoherenceResult>({
max: 1000,
ttl: 60000 // 1 minute TTL
});
// Cache key generation
function getCacheKey(vectors: Float32Array[]): string {
const hash = crypto.createHash('sha256');
for (const v of vectors) {
hash.update(Buffer.from(v.buffer));
}
return hash.digest('hex');
}
Batch Processing
// Batch coherence validation for efficiency
async function batchValidate(
entries: MemoryEntry[],
batchSize: number = 10
): Promise<CoherenceValidation[]> {
const results: CoherenceValidation[] = [];
for (let i = 0; i < entries.length; i += batchSize) {
const batch = entries.slice(i, i + batchSize);
const batchResults = await Promise.all(
batch.map(e => coherenceGate.validate(e))
);
results.push(...batchResults);
}
return results;
}
Async Processing
// Non-blocking stability analysis
async function analyzeStabilityAsync(swarmId: string): Promise<void> {
// Queue analysis for background processing
await queue.add('stability-analysis', {
swarmId,
priority: 'normal'
});
}
// Background worker
queue.process('stability-analysis', async (job) => {
const { swarmId } = job.data;
const analysis = await stabilityAnalyzer.analyze(swarmId);
// Store results
await memory.store({
namespace: 'pr/stability-metrics',
key: `swarm-${swarmId}-${Date.now()}`,
content: JSON.stringify(analysis)
});
// Emit event if unhealthy
if (!analysis.isHealthy()) {
eventBus.emit('StabilityThresholdBreached', {
type: 'StabilityThresholdBreached',
timestamp: new Date(),
analysisId: analysis.id,
sourceType: 'swarm',
sourceId: swarmId,
spectralGap: analysis.spectralGap.getValue(),
recommendations: analysis.recommendations
});
}
});
Related Documentation
- README - Domain overview
- Domain Model - Entities and aggregates
- ADR-031: Prime Radiant Integration
- ADR-006: Unified Memory Service
- ADR-022: AIDefence Integration