Aletheia: Weekend Sprint Report¶

Period: February 6-8, 2026 Author: David Morales

Executive Summary¶

Over a three-day sprint, we transformed Aletheia's LLM-accessible interface from a basic search tool into a full analytics platform. We forked our core dependency (Graphiti) to gain control over release cadence and quality, integrated 16 community bug fixes and features, built a Cypher query engine for direct graph analytics, and made every connector self-describing so that LLMs understand each domain's data without manual prompting.

What Changed and Why It Matters¶

1. Independence from upstream release cycles¶

We created and maintain our own fork of Graphiti. Previously, bug fixes required waiting for the upstream maintainer's release schedule (weeks to months). We now control when fixes ship. We also built a repeatable process (codified as a Claude Code skill) for pulling future upstream improvements.

2. LLMs can now do analytics, not just search¶

Before this sprint, LLMs connected to our knowledge graphs could only perform semantic search -- "find entities similar to X." Now they can run structured Cypher queries against the graph ("count all sanctions by jurisdiction," "find the shortest path between two entities"), inspect the graph schema, and combine search with analytics in multi-step workflows. A four-stage security pipeline ensures all queries are read-only.

3. Connectors describe themselves¶

Each MCP connector now introspects its own graph at startup and generates domain-specific tool descriptions, entity catalogs, and example queries. An LLM connecting to the Aviation Safety graph sees aviation-specific guidance; the same code connecting to Terrorist Organizations sees sanctions-specific guidance. This eliminates the need for manual prompt engineering per domain.

4. Quality hardened across multiple domains¶

We ran the full pipeline against our richest dataset (Operation Tango: 491 records, 18 entity schemas, 3 sanctions jurisdictions) and fixed 12 issues in entity extraction, deduplication, and edge resolution. These fixes benefit all current and future use cases.

Delivery Metrics¶

Risks and Next Steps¶

• Fork maintenance: We now own the merge burden. The upstream-fork-sync skill mitigates this but periodic syncs require attention.
• Cypher security: The whitelist-based security gate is conservative by design. Edge cases from production LLM queries will grow the regression test suite organically.
• Integration testing: Cypher tools have unit tests and stubs but no live FalkorDB integration tests yet. These should be added before any production deployment.

Full Technical Report¶

Context¶

Coming into Friday, Aletheia was running on upstream graphiti-core from PyPI and had 6 use cases (anticorruption, terrorist_orgs, aviation_safety, safety_recommendations, airworthiness_directives, operation_tango). The MCP server was the stock Graphiti one with minimal search tools. Schema inference had grown to include Phase 4 consolidation but was still hitting LLM non-determinism issues.

1. Create the Aletheia-Graphiti Fork¶

Why: Upstream Graphiti had 20+ open PRs with fixes we needed, plus we had our own fixes that couldn't go upstream (prompt changes, FalkorDB-specific edge type handling). Running on PyPI releases meant waiting months for bug fixes.

What we did: - Forked getzep/graphiti to david-morales/aletheia-graphiti (branch: aletheia) - Pointed aletheia's dependency at the fork with force-reinstall workflow - Versioned as 0.27.0rc2 to stay ahead of upstream releases

2. Analyze Open PRs and Cherry-Pick the Best¶

What we did: Analyzed all ~25 open PRs on getzep/graphiti, triaged for relevance, and cherry-picked 16 upstream PRs into our fork:

Created the upstream-fork-sync skill (~/.claude/skills/upstream-fork-sync/) to systematize this process for future syncs: discover new PRs, triage what's integrated, plan cherry-picks with human approval, execute with TDD.

3. Revamp the MCP Server (Complete Overhaul)¶

Before: Stock Graphiti MCP with search_nodes, search_memory_facts, get_entity_edge -- three narrow tools with no ontology awareness, no Cypher, no schema introspection.

After: 6 main tools + 7 secondary tools, fully self-describing per domain. ~80 commits on the fork.

3a. Tool Surface Redesign (Feb 7)¶

• Unified search tool replacing 3 separate ones -- supports node, edge, and community search in one call with configurable search_mode, reranker, source, depth
• explore_node -- entity-centric graph exploration with BFS traversal
• get_episode_context and build_communities -- new tools
• Bulk episode ingestion added to add_memory
• Tightened schemas with Literal types, added YAML-configurable search defaults
• 40+ unit tests for the new tools

3b. Ontology Graph Integration (Feb 8)¶

• search_ontology + explore_ontology -- same patterns as KG tools but against a companion ontology graph
• Config field ontology_graph connects each KG server to its ontology
• Dynamic server naming: mcp._mcp_server.name = f'Graphiti - {group_id}'

3c. Self-Describing Connectors via DomainProfile (Feb 8)¶

• DomainProfile dataclass auto-discovers entity types, edge types, counts, and samples from the graph at startup
• Enriches descriptions from ontology graph if configured
• 3 MCP resources: graphiti://domain_summary, graphiti://entity_catalog, graphiti://relationship_types
• Dynamic tool descriptions generated from profile (each domain gets custom search examples, entity type lists)
• Graceful fallback: static docstrings if introspection fails
• Reasoning-style "When to use / When NOT to use" docstrings for all tools

3d. Layered Config (Feb 8)¶

• base: key in YAML overlay loads and deep-merges a shared config
• Shared base config (mcp-base-config.yaml) in aletheia with LLM, embedder, database, transport
• 4 domain-specific overlays in aletheia use_cases/<name>/mcp_config.yaml

3e. Cypher Analytics Pipeline (Feb 8) -- 13-task plan executed with subagent-driven development¶

• get_schema -- structural schema discovery with dirty-flag cache (invalidated on all data-modifying operations)
• run_cypher -- read-only Cypher via GRAPH.RO_QUERY with 4-stage validation pipeline:
• Stage 1: LLM syntax fixups (smart quotes, code blocks, identifier quoting, RETURN injection)
• Stage 2: FalkorDB dialect (reject APOC/pattern comprehensions/EXISTS{}, auto-fix date→string/toLower)
• Stage 3: Security whitelist (fail-safe, only known read-only keywords allowed)
• Stage 4: Safety injection (LIMIT N+1 for truncation detection)
• Typed result envelopes (scalar, tabular, graph, path formats)
• format_error() with stage/reason/explanation/suggestion/doc_hint
• 95 unit tests + 3 integration stubs + 1 regression fixture = 175 total MCP tests

4. Debug and Harden the Fork Across Use Cases¶

Ran operation_tango (491 records, 18 FTM schemas) and aviation_safety use cases against the fork. Found and fixed 12 issues in graphiti-core:

5. Schema Inference Improvements (Aletheia-side)¶

6. Update Documentation¶

• MCP landing page (docs/mcp/index.md) -- connector table, overview
• MCP connectors reference (docs/mcp/connectors.md, ~2500 words) -- comparison tables (Graphiti stock vs Aletheia), capability matrix, self-describing connector architecture, tool reference, Cypher pipeline with Mermaid diagram, FalkorDB dialect cheatsheet, cross-graph workflow patterns, performance data
• GraphRAG-SDK comparison (docs/comparisons/graphrag-sdk.md) -- functional comparison of ontology approaches
• Updated mkdocs.yml nav and docs/index.md feature table
• Build verified with mkdocs build --strict, deployed to Netlify

By the Numbers¶