git-mind 🧠

A Git-integrated knowledge graph for tracking relationships between code artifacts.

🚧 MAJOR ARCHITECTURAL MIGRATION IN PROGRESS 🏗️

We’re transforming git-mind from a monolithic CLI into a clean, embeddable C library with zero warnings under extreme compiler strictness.

Progress: Core library 50% complete | CLI separation 0% | New apps 0%

See The Great Migration below for details.

---

What is git-mind?

git-mind captures and versions the connections between your code, documentation, and design artifacts. It stores these relationships as Git objects, making them as permanent and trackable as your code.

# Link a design document to its implementation
git mind link docs/auth-flow.md src/auth.c --type implements

# Find all code that implements a specific design
git mind traverse docs/auth-flow.md --direction forward

# See how your understanding evolved
git checkout v1.0
git mind list  # View connections from that point in time

---

Installation

From Source

git clone https://github.com/neuroglyph/git-mind
cd git-mind
meson setup build
ninja -C build
sudo ninja -C build install

Requirements

• Git 2.28+
• C23-compliant compiler (GCC 12+ or Clang 16+)
• Meson build system
• Ninja
• libsodium
• libgit2 (for Git object manipulation)

Core Concepts

• Links: Directed relationships between files (e.g., “implements”, “documents”, “tests”)
• Traversal: Navigate your codebase through semantic connections, not just file paths
• Time Travel: Your knowledge graph evolves with your code - checkout any commit to see that era’s understanding

Usage

Creating Links

# Basic link creation
git mind link <source> <target> --type <relationship>

# Common relationship types
git mind link README.md src/main.c --type documents
git mind link test_auth.c src/auth.c --type tests
git mind link design.md src/module/ --type implements

Exploring Connections

# List all links
git mind list

# Find what a file connects to
git mind traverse src/auth.c

# Find what connects to a file
git mind traverse src/auth.c --direction backward

# Filter by relationship type
git mind list --type tests

Advanced Features

# Export knowledge graph
git mind export --format dot > graph.dot

# Check link integrity
git mind verify

# Remove broken links
git mind prune

Architecture

git-mind stores relationship data in .git/refs/minds/ using Git’s object database. Each link is a Git object containing:

• Source and target paths
• Relationship type
• Creation timestamp
• Optional metadata

This design ensures links are:

• Version controlled
• Distributed with the repository
• Preserved through Git operations
• Queryable at any point in history

---

Development

Building

# Standard build
meson setup build
ninja -C build

# Debug build
meson setup build_debug -Dbuildtype=debug
ninja -C build_debug

# Run tests
ninja -C build test

Code Organization

core/           # Core library implementation
├── include/    # Public headers
├── src/        # Implementation
└── tests/      # Unit tests

cli/            # Command-line interface
tools/          # Development utilities
docs/           # Documentation

Contributing

See CONTRIBUTING

---

🚧 The Great Migration

Why We’re Migrating

We started with 11,951 compiler warnings - a technical debt mountain that was holding us back. Rather than patch over problems, we’re rebuilding git-mind with extreme code quality standards:

• Zero Warnings Policy: Every module in core/ must have ZERO clang-tidy warnings
• GNU CRY GAUNTLET: Our CI runs the strictest compiler settings that “make GNU developers cry”
• C23 Standard: Leveraging the latest C standard for better type safety and modern features
• Library-First Design: Transform from monolithic CLI to embeddable C library
• Single-Header Core: Ultimate goal is a single #include <gitmind.h> for all functionality

Migration Milestones

🎯 Milestone 1: “Core Complete” (~50% done)

Status: 🟩🟩🟩🟩🟩⬜⬜⬜⬜⬜
Target: January 2025

✅ Completed (Warning-Free™)

• Error handling, Result types
• Type system (paths, strings, IDs, ULID)
• Crypto backend (pluggable)
• Time operations (mockable)
• CBOR encoding
• UTF-8 validation
• I/O operations

🚧 Remaining for Core Library

• Edge system (graph operations) - ~50 warnings
• Attribution (authorship) - ~50 warnings
• Journal system (Git object storage)
• Cache system (query optimization)

🎯 Milestone 2: “CLI: Oh My!” (0% done)

Status: ⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜
Target: February 2025

📋 Application Separation Tasks

• Extract CLI from src/cli/ to apps/cli/
• Extract Git hooks to apps/hooks/
• Create proper libgit2 integration layer
• Implement against libgitmind API
• Add modern CLI features (colors, progress bars)

🎯 Milestone 3: “Beyond CLI” (0% done)

Status: ⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜
Target: March 2025

🚀 New Applications

• MCP server for AI integration
• Web UI daemon
• Git hooks as separate binaries
• Language bindings (Python, Rust)

Current Components (Being Migrated)

src/
├── core/           # ✅ Low-level utilities (50% migrated)
├── edge/           # 🚧 Graph operations (edges, relationships)
├── attribution/    # 🚧 Authorship tracking
├── journal/        # 📋 Git object storage (read/write edges)
├── cache/          # 📋 Query optimization layer
├── cli/            # 📋 Command-line interface
└── hooks/          # 📋 Git hooks (post-commit, etc.)

Target Architecture

git-mind/
├── libgitmind/     # Single-header library
│   ├── core/       # Foundation (types, crypto, I/O)
│   ├── graph/      # Graph operations (edges, attribution)
│   └── storage/    # Git persistence (journal, cache)
├── apps/
│   ├── cli/        # Command-line interface
│   ├── hooks/      # Git hooks (separate binaries)
│   ├── mcp/        # Model Context Protocol server
│   └── web/        # Web UI daemon
└── bindings/       # Language bindings (Python, Rust, etc.)

🚀 Beyond Migration: Coming Soon

🧠 Semantic Intelligence (Q2 2025)

• AI-Powered Discovery: Automatically detect and suggest relationships between code artifacts
• Natural Language Queries: “Show me all code that implements authentication”
• Intelligent Refactoring: Track concept migrations across architectural changes

🌐 Distributed Knowledge (Q3 2025)

• Cross-Repository Links: Connect knowledge across project boundaries
• Federated Graphs: Share and merge knowledge graphs between teams
• Knowledge Synchronization: Keep understanding in sync across distributed teams

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: docs/

---

License

Licensed under LicenseRef-MIND-UCAL-1.0. See LICENSE file for details.

© 2025 – J. Kirby Ross • https://github.com/flyingrobots