MUSUBIX - Neuro-Symbolic AI Integration System

Next-generation AI Coding System powered by Git-Native Knowledge Integration

v3.8.1 - 25 packages, 107 MCP tools, 5,738+ tests

日本語版 README

Overview

MUSUBIX is an innovative AI coding system that integrates Neural (LLM) and Symbolic (Knowledge Graph) reasoning. It combines MUSUBI SDD methodology with Git-native knowledge management to support high-quality software development.

🎉 v3.8 Highlights

• 25 packages - Comprehensive neuro-symbolic AI development toolkit
• 107 MCP tools - SDD, Pattern, Knowledge, Policy, Decision, Synthesis, Workflow, Agent, Skill tools
• 5,738+ tests - All passing across 25 packages
• 13 Agent Skills - Claude Code integration for SDD workflow automation
• Monorepo optimizations - Unified tsc -b builds, standardized dependencies, Prettier formatting
• Deep Research - AI-driven iterative research system with 6 integration modules
• Git-Native Knowledge - File-based knowledge graph in .knowledge/ (zero dependencies)
• Codegraph - Code structure analysis supporting 16 languages

Features

• 🧠 Neuro-Symbolic Integration - Fusion of LLM creativity and knowledge graph precision
• 📂 Git-Native Knowledge - File-based knowledge graph management (v3.0.0)
• 📊 DFG/CFG Analysis - Data flow and control flow graph extraction for TypeScript/JavaScript
• 🧮 Lean 4 Integration - Formal theorem proving with EARS-to-Lean conversion
• 📚 Library Learning - DreamCoder-style hierarchical abstraction and pattern compression
• 🔍 Neural Search - Neural-guided program synthesis with beam search
• ⚗️ Program Synthesis - DSL-based PBE synthesis with witness functions
• 🔒 Symbolic Reasoning - Formal verification, hallucination detection, constitution enforcement
• 📝 EARS Requirements Analysis - Conversion and validation from natural language to formal requirements
• 🎨 Design Pattern Recommendations - Context-based C4 model and ADR generation
• ✅ Test-Driven Development - Quality assurance through Test-First principles
• 🔗 Complete Traceability - Tracking from requirements to code
• 🛡️ Security Analysis - Vulnerability scanning, secret detection, taint analysis (v1.8.0)
• 🔬 Formal Verification - Z3 SMT solver integration, Hoare triple verification (v1.7.5)
• 🖥️ Interactive REPL - Command completion, history, session variables (v1.6.0)
• 🔮 Advanced Inference - OWL 2 RL reasoning and Datalog evaluation (v1.4.5)

Architecture

flowchart TB
    subgraph MUSUBIX["MUSUBIX System v3.8"]
        subgraph Core["Core"]
            CLI["musubix CLI"]
            CoreLib["@nahisaho/musubix-core"]
            Knowledge["@musubix/knowledge"]
        end

        subgraph Agent["Agent Layer"]
            MCP["@nahisaho/musubix-mcp-server\n107 tools"]
            Orchestrator["Agent Orchestrator"]
            Skills["Skill Manager"]
        end

        subgraph Learning["Learning"]
            WakeSleep["Wake-Sleep"]
            DeepResearch["Deep Research"]
        end

        subgraph Security["Verification"]
            SecPkg["Security Analysis"]
            FormalVerify["Formal Verification"]
        end

        CLI --> CoreLib
        CoreLib <--> MCP
        MCP <--> Orchestrator
        Orchestrator <--> Skills
        CoreLib --> Knowledge
        CoreLib --> Learning
        CoreLib --> Security
    end

Project Structure

| Path | Description | |------|-------------| | packages/core/ | Core library (249 modules) | | packages/core/auth/ | Authentication & Authorization | | packages/core/cli/ | CLI Interface | | packages/core/codegen/ | Code Generation & Analysis | | packages/core/design/ | Design Patterns & C4 Models | | packages/core/error/ | Error Handling | | packages/core/explanation/ | Explanation Generation & Visualization | | packages/core/learning/ | Self-Learning & Pattern Extraction | | packages/core/requirements/ | Requirements Analysis & Decomposition | | packages/core/symbolic/ | Symbolic Reasoning | | packages/core/traceability/ | Traceability | | packages/core/types/ | Type Definitions | | packages/core/utils/ | Utilities | | packages/core/validators/ | EARS Validation | | packages/mcp-server/ | MCP Server (107 tools, 5 prompts) | | packages/security/ | Security Analysis | | packages/formal-verify/ | Formal Verification | | packages/pattern-mcp/ | Pattern Learning | | packages/ontology-mcp/ | Ontology Engine | | packages/wake-sleep/ | Wake-Sleep Learning | | packages/sdd-ontology/ | SDD Ontology | | packages/dfg/ | DFG/CFG Extraction - Data Flow Analysis | | packages/lean/ | Lean 4 Integration - Theorem Proving | | packages/library-learner/ | Library Learning - DreamCoder-style | | packages/neural-search/ | Neural Search - Guided Synthesis | | packages/synthesis/ | Program Synthesis - DSL/PBE | | packages/agent-orchestrator/ | Agent Orchestrator - Sub-agent Distribution | | packages/workflow-engine/ | Workflow Engine - 5-Phase Control | | packages/skill-manager/ | Skill Manager - Dynamic Skill Loading | | packages/codegraph/ | Codegraph - Code Structure Analysis (16 languages) | | packages/expert-delegation/ | Expert Delegation - 7 AI Expert Types | | packages/deep-research/ | Deep Research - AI-driven Iterative Research | | packages/assistant-axis/ | Assistant Axis - Multimodal Integration | | packages/musubi/ | Musubi - AI Summarization | | packages/knowledge/ | Knowledge Store - Git-friendly JSON Graph | | packages/policy/ | Policy Engine - 9 Constitutional Articles | | packages/decisions/ | Decision Records - ADR Management | | steering/ | Project Memory | | storage/ | Specifications & Artifacts | | templates/ | Templates | | docs/ | Documentation |

Requirements

• Node.js >= 20.0.0
• npm >= 10.0.0
• TypeScript >= 5.3

Installation

npm/npx (Recommended)

# Global installation
npm install -g musubix

# Run directly with npx
npx musubix init
npx musubix --help

# Start MCP Server
npx @nahisaho/musubix-mcp-server
npx musubix-mcp --transport stdio

Scoped Packages

# Install individual packages
npm install @nahisaho/musubix-core
npm install @nahisaho/musubix-mcp-server
npm install @nahisaho/musubix-security
npm install @nahisaho/musubix-formal-verify
npm install @musubix/knowledge
npm install @musubix/decisions
npm install @musubix/policy

Build from Source

git clone https://github.com/nahisaho/MUSUBIX.git
cd MUSUBIX
npm install
npm run build

Development

# Build
npm run build

# Run tests
npm test

# Lint
npm run lint

# Type check
npm run type-check

Key Features

Requirements Definition (Article II Compliant)

• EARS Validation: Easy Approach to Requirements Syntax pattern validation
• Interactive Q&A Hearing: Dialogue-based requirements gathering
• Requirements Decomposition: Breaking down large requirements into implementation units
• Related Requirements Search: Automatic detection of similar and dependent requirements

Design Generation (Article III Compliant)

• C4 Model Generation: Context/Container/Component/Code diagrams
• ADR Generation: Architecture Decision Records
• Pattern Detection: Automatic detection and recommendation of design patterns
• SOLID Validation: SOLID principle compliance checking

Code Generation & Verification

• Static Analysis: Quality metrics and complexity calculation
• Security Scanning: Vulnerability detection
• Test Generation: Unit and integration test generation
• Coverage Reporting: Test coverage measurement

MCP Server

Provides 107 tools and 5 prompts covering SDD, Pattern, Knowledge, Policy, Decision, Synthesis, Workflow, Agent, and Skill management:

# Start MCP Server
npx @nahisaho/musubix-mcp-server

Documentation

| Document | Description | |----------|-------------| | Requirements Specification | EARS format functional/non-functional requirements | | Design Document | C4 model and ADR-based design | | Task Definition | 56 tasks sprint plan | | API Reference | Public API specification | | Symbolic Integration | Neuro-Symbolic requirements (27 requirements) |

Symbolic Reasoning Module (v1.2.0)

The new symbolic reasoning module provides:

Phase 1: Foundation

• SemanticCodeFilterPipeline - LLM output semantic validation
• HallucinationDetector - Undefined symbol/invalid import detection
• ConstitutionRuleRegistry - 9 Constitution articles enforcement
• ConfidenceEstimator - AST complexity, requirement coverage scoring
• ConfidenceBasedRouter - Confidence-based routing decisions
• ErrorHandler - Graceful degradation

Phase 2: Formal Verification

• EarsToFormalSpecConverter - EARS → SMT-LIB conversion
• VerificationConditionGenerator - Verification condition (VC) generation
• Z3Adapter - Z3 SMT solver integration
• SecurityScanner - OWASP patterns, secret detection

Phase 3: Advanced Features

• CandidateRanker - Multi-criteria candidate scoring
• ResultBlender - Neural/Symbolic result integration (3 strategies)
• ExtensibleRuleConfig - YAML/JSON rule configuration
• AuditLogger - SHA-256 hash-chain tamper detection
• PerformanceBudget - Step-level budgets, SLO metrics
• QualityGateValidator - Automated quality gate validation

Wake-Sleep Learning Cycle (v1.3.0)

Continuous learning system based on the Wake-Sleep algorithm:

| Phase | Processing | |-------|------------| | Wake | Code observation → Pattern extraction → Knowledge graph update | | Sleep | Pattern consolidation → Similar pattern compression → Memory optimization |

Key Components

• WakeSleepCycle - Learning cycle orchestration
• PatternLibrary - Persistent pattern storage management
• PatternOntologyBridge - Pattern ↔ Ontology bidirectional conversion
• N3Store - RDF/OWL-based knowledge graph storage

New MCP Tools (7 tools)

• pattern_extract - Extract patterns from code
• pattern_compress - Abstraction and compression of patterns
• pattern_store - Save to pattern library
• pattern_query - Search and retrieve patterns
• pattern_consolidate - Consolidate similar patterns
• ontology_query - Query ontology graph
• ontology_infer - Execute ontology-based inference

Advanced Inference (v1.4.5)

OWL 2 RL profile reasoning and Datalog evaluation engine:

Inference Components

• OWL2RLReasoner - OWL 2 RL profile compliant inference (20+ built-in rules)
• DatalogEngine - Stratified Datalog evaluation with negation support
• InferenceExplainer - Human-readable inference explanation generator
• ProgressReporter - Real-time progress feedback (500ms interval)

OWL 2 RL Built-in Rules

| Category | Rules | Description | |----------|-------|-------------| | Class Axioms | cax-sco, cax-eqc | Subclass, Equivalent class inference | | Property | prp-dom, prp-rng | Domain, Range inference | | Property Characteristics | prp-symp, prp-trp, prp-inv | Symmetric, Transitive, Inverse | | Equality | eq-ref, eq-sym, eq-trans | sameAs inference |

Explanation Formats

• text - Plain text explanation
• markdown - Markdown format
• html - HTML format with escaping

Constitutional Articles (9 Articles)

MUSUBIX adheres to the following 9 constitutional articles:

1. Specification First - Requirements before implementation
2. Design Before Code - Design before coding
3. Single Source of Truth - Project memory is authoritative
4. Traceability - Tracking from requirements to code
5. Incremental Progress - Small, frequent deliveries
6. Decision Documentation - Decisions recorded as ADRs
7. Quality Gates - Phase validation required
8. User-Centric - Document user value
9. Continuous Learning - Retrospectives and improvements

License

MIT License - See LICENSE for details

Author

nahisaho

Changelog

See CHANGELOG.md

---

Document ID: README Version: 3.8.1 Last Updated: 2026-02-08