mcp_fact_graph 0.1.1

Temporal knowledge graph with evidence-based fact management, candidate confirmation, and automatic summarization for the MCP ecosystem.

MCP Fact Graph

Support This Project

If you find this package useful, consider supporting ongoing development on PayPal.

Support makemind via PayPal

---

MCP Knowledge Package Family

• mcp_bundle: Bundle schema, loader, validator, and expression language for MCP ecosystem.
• mcp_fact_graph: Temporal knowledge graph with evidence-based fact management and summarization.
• mcp_skill: Skill definitions and runtime execution for AI capabilities.
• mcp_profile: Profile definitions for AI personas with template rendering and appraisal.
• mcp_knowledge_ops: Knowledge operations including pipelines, workflows, and scheduling.
• mcp_knowledge: Unified integration package for the complete knowledge system.

---

A powerful Dart package for temporal knowledge representation with evidence-based facts, candidates, and automatic summarization. Part of the MakeMind MCP ecosystem.

Features

Core Features

• Temporal Knowledge Graph: Track facts with full temporal context and validity periods
• Evidence-Based Facts: Link facts to supporting evidence with confidence scores
• Candidate Management: Handle pending facts awaiting confirmation
• Claim Recording: Record assertions from skill executions

Data Model

• Facts: Confirmed knowledge with domain, category, and temporal scope
• Evidence: Raw data sources supporting facts
• Candidates: Pending fact proposals awaiting confirmation
• Claims: Assertions generated by skill executions
• Summaries: Auto-generated or manual summaries per entity

Advanced Features

• Context Bundles: Retrieve complete entity context for LLM consumption
• Summarization: Automatic and manual summary generation
• Port-Based Architecture: Clean dependency injection via ports
• Query Support: Flexible fact querying by entity, domain, and time

Quick Start

Installation

Add to your pubspec.yaml:

dependencies:
  mcp_fact_graph: ^0.1.0

Basic Usage

import 'package:mcp_fact_graph/mcp_fact_graph.dart';

void main() async {
  // Create storage ports
  final ports = FactGraphPorts(
    factStorage: InMemoryFactStorage(),
    evidenceStorage: InMemoryEvidenceStorage(),
    candidateStorage: InMemoryCandidateStorage(),
    entityStorage: InMemoryEntityStorage(),
    eventStorage: InMemoryEventStorage(),
    viewStorage: InMemoryViewStorage(),
  );

  // Create fact graph service
  final factGraph = FactGraphService(ports: ports);

  // Ingest evidence
  final evidence = Evidence(
    id: 'ev_001',
    sourceType: 'conversation',
    content: 'User mentioned they prefer dark mode',
    timestamp: DateTime.now(),
  );
  await factGraph.ingestEvidence(evidence);

  // Create and confirm a fact
  final candidate = Candidate(
    id: 'cand_001',
    entityId: 'user_123',
    domain: 'preferences',
    category: 'ui',
    value: {'darkMode': true},
    confidence: 0.9,
    evidenceIds: ['ev_001'],
  );
  await factGraph.createCandidate(candidate);
  final fact = await factGraph.confirmCandidate('cand_001');

  // Query facts
  final userFacts = await factGraph.queryFacts(
    entityId: 'user_123',
    domain: 'preferences',
  );

  // Get entity context bundle
  final context = await factGraph.getContextBundle('user_123');
}

Core Concepts

Facts

Facts represent confirmed knowledge about entities:

final fact = Fact(
  id: 'fact_001',
  entityId: 'user_123',
  domain: 'preferences',
  category: 'theme',
  value: {'darkMode': true, 'fontSize': 14},
  confidence: 0.95,
  validFrom: DateTime.now(),
  evidenceIds: ['ev_001', 'ev_002'],
);

Evidence

Evidence provides the source data for facts:

final evidence = Evidence(
  id: 'ev_001',
  sourceType: 'conversation',
  mimeType: 'text/plain',
  content: 'User said: I prefer dark mode',
  timestamp: DateTime.now(),
  metadata: {'conversationId': 'conv_123'},
);

Candidates

Candidates are pending facts awaiting confirmation:

final candidate = Candidate(
  id: 'cand_001',
  entityId: 'user_123',
  domain: 'preferences',
  category: 'theme',
  value: {'darkMode': true},
  confidence: 0.85,
  evidenceIds: ['ev_001'],
  status: CandidateStatus.pending,
);

Claims

Claims are assertions from skill executions:

final claim = Claim(
  id: 'claim_001',
  skillId: 'preference_extractor',
  executionId: 'exec_001',
  entityId: 'user_123',
  domain: 'preferences',
  value: {'darkMode': true},
  confidence: 0.9,
);

Context Bundles

Context bundles provide complete entity context for LLM consumption:

final bundle = await factGraph.getContextBundle('user_123');

// Access structured data
final facts = bundle.facts;
final summary = bundle.summary;
final recentClaims = bundle.recentClaims;

Port-Based Architecture

The package uses a port-based dependency injection pattern:

// Define custom storage implementation
class MyFactStorage implements FactStoragePort {
  @override
  Future<Fact?> getFact(String id) async { /* ... */ }

  @override
  Future<void> saveFact(Fact fact) async { /* ... */ }

  @override
  Future<List<Fact>> queryFacts(FactQuery query) async { /* ... */ }
}

// Inject custom ports
final ports = FactGraphPorts(
  factStorage: MyFactStorage(),
  evidenceStorage: MyEvidenceStorage(),
  // ...
);

API Reference

FactGraphService

Method	Description
ingestEvidence(evidence)	Ingest new evidence
createCandidate(candidate)	Create a pending candidate
confirmCandidate(id)	Confirm candidate as fact
rejectCandidate(id, reason)	Reject a candidate
queryFacts(...)	Query facts with filters
getContextBundle(entityId)	Get complete entity context
recordClaims(claims)	Record skill claims
updateSummary(entityId)	Update entity summary

Examples

Complete Examples Available

• example/basic_usage.dart - Basic fact graph operations
• example/evidence_ingestion.dart - Evidence processing workflow
• example/context_bundle.dart - Context bundle generation

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Support

• Documentation
• Issue Tracker
• Discussions
• Support on Patreon

License

This project is licensed under the MIT License - see the LICENSE file for details.