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:

Specification First - Requirements before implementation
Design Before Code - Design before coding
Single Source of Truth - Project memory is authoritative
Traceability - Tracking from requirements to code
Incremental Progress - Small, frequent deliveries
Decision Documentation - Decisions recorded as ADRs
Quality Gates - Phase validation required
User-Centric - Document user value
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

Name		Name	Last commit message	Last commit date
Latest commit History 208 Commits
.claude-flow/metrics		.claude-flow/metrics
.claude		.claude
.github		.github
.knowledge-sample		.knowledge-sample
.knowledge		.knowledge
.musubix		.musubix
.reports		.reports
.swarm		.swarm
bin		bin
docker		docker
docs		docs
examples		examples
packages		packages
scripts		scripts
steering		steering
storage		storage
virtual-projects		virtual-projects
.gitignore		.gitignore
.musubix_history		.musubix_history
.npmrc		.npmrc
.prettierignore		.prettierignore
.prettierrc		.prettierrc
.yata-local.db		.yata-local.db
001.lean		001.lean
002.lean		002.lean
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.ja.md		README.ja.md
README.md		README.md
RELEASE-NOTES-v1.0.1.md		RELEASE-NOTES-v1.0.1.md
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.base.json		tsconfig.base.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

License

nahisaho/MUSUBIX

Folders and files

Latest commit

History

Repository files navigation

MUSUBIX - Neuro-Symbolic AI Integration System

Overview

🎉 v3.8 Highlights

Features

Architecture

Project Structure

Requirements

Installation

npm/npx (Recommended)

Scoped Packages

Build from Source

Development

Key Features

Requirements Definition (Article II Compliant)

Design Generation (Article III Compliant)

Code Generation & Verification

MCP Server

Documentation

Symbolic Reasoning Module (v1.2.0)

Phase 1: Foundation

Phase 2: Formal Verification

Phase 3: Advanced Features

Wake-Sleep Learning Cycle (v1.3.0)

Key Components

New MCP Tools (7 tools)

Advanced Inference (v1.4.5)

Inference Components

OWL 2 RL Built-in Rules

Explanation Formats

Constitutional Articles (9 Articles)

License

Author

Changelog

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages