Warning
This project is in its early stages — USE AT YOUR OWN RISK.
Right now you can’t do much with it yet, and it does make changes inside your Git repo.
Proceed only if you’re curious and comfortable experimenting.
This README is more of a Vision Statement™ than a manual. It’s here to set the direction, hype the idea, and motivate ongoing work.
If you’re intrigued, star the repo ⭐, follow along in Discussions/Releases, and watch it grow.
— flyingrobots
Version your thoughts. Branch your ideas. Merge understanding.
git-mind transforms any Git repository into a serverless knowledge graph, where relationships evolve with your history and AI helps uncover hidden connections.
No servers. No setup. Just git push your mind.
# "What implements our authentication?"
$ git mind query --implements "auth-flow.md"
core/src/auth.c (verified, 2 days ago)
tests/auth.test.c (verified, 2 days ago)
core/src/oauth.c (AI suggested, 1 hour ago)
# See how your understanding evolved
$ git checkout main~30
$ git mind query --implements "auth-flow.md"
basic_auth.c (30 days ago)
$ git checkout main
$ git mind query --implements "auth-flow.md"
oauth2.c
jwt_handler.c
basic_auth.c
# Your knowledge graph evolved with your code!# Connect ideas as you write
$ git mind link notes/quantum.md papers/bell-1964.pdf --type cites
$ git mind link notes/quantum.md notes/entanglement.md --type explores
# Discover thought patterns
$ git mind query "ideas without connections"
notes/orphaned-thought.md (created 3 weeks ago)
notes/random-insight.md (created 1 month ago)# Fork someone's knowledge graph
$ git clone https://github.com/alice/research.git
$ git mind explore --author alice
423 concepts, 1,247 connections
# Merge understanding
$ git merge bob/authentication-redesign
Merging 47 new semantic edges...
3 conflicts in knowledge graph (view with: git mind conflicts)Install/build instructions: see docs/install.md.
Warning
DO NOT BUILD GITMIND OUTSIDE OF DOCKER git-mind manipulates Git internals (refs/*, objects, config). Building or running tests on the host can corrupt this repository or others on your machine. Always use the CI Docker image for safety and parity.
[!INFO] If you really want to... Use the container workflow:
make ci-local— docs checks + build + unit tests in the CI imagetools/ci/ci_local.sh— same as above, direct Advanced (at your own risk):meson setup build -Dforce_local_builds=true— explicit Meson overrideGITMIND_ALLOW_HOST_BUILD=1— legacy env override (discouraged)
CLI examples (subset implemented today):
# Start linking
git mind link README.md core/src/main.c --type documents
git mind link core/src/auth.c tests/auth.test.c --type "tested-by"
# Explore connections
git mind list --from core/src/auth.c
# Rebuild cache when needed
git mind cache-rebuildPackage managers (Homebrew/Winget): coming soon.
👉 For a hands-on walkthrough, see docs/tutorial.md.
- Your repo is the database — No servers, no external dependencies
- Time-travel built in — Check out any commit, get the graph from that moment
- AI copilot ready — Let AI suggest connections, you review and merge
- Branch and merge ideas — Try wild connections in a branch, merge what works
Software Architecture
- Trace decisions through code
- See which tests cover which requirements
- Understand impact before refactoring
Research & Writing
- Build Zettelkasten-style note networks
- Track citation graphs
- Fork and extend others' research
Team Knowledge
- Onboard developers with explorable codebases
- Preserve institutional memory in the repo
- Share mental models through PRs
git-mind treats AI as a collaborator with clear attribution:
# AI suggests connections in a branch
$ git checkout -b ai/suggestions
$ git mind ai discover
Found 23 potential connections...
# You review and cherry-pick
$ git mind review --source ai
core/src/cache.c implements docs/caching-strategy.md (confidence: 0.92)
[Accept/Reject/Skip]? a
# Clear attribution preserved
$ git mind list --from core/src/cache.c --format json
{
"to": "docs/caching-strategy.md",
"type": "implements",
"author": "ai-assistant",
"verified_by": "james",
"timestamp": "2024-11-08T10:30:00Z"
}docs/install.md— Install/build locallydocs/tutorial.md— Hands‑on walkthroughdocs/philosophy.md— Why we built thisdocs/TECHNICAL.md— How it works under the hoodCONTRIBUTING.md— PRs welcome!
- 🧪 Early adopters exploring Zettelkasten workflows in Git
- 🔬 Researchers mapping papers → datasets → results
- 💻 Dev teams linking docs ⇄ code ⇄ tests
- 🧠 Individuals experimenting with personal knowledge graphs
Want to be featured? Open an issue and share your story.
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 0%
🚀 Early release — Core features work today, API may evolve
📅 Roadmap: docs/roadmap.md
🤝 Contributing: CONTRIBUTING.md
git-mind emerged from a simple observation: we spend enormous effort understanding code, then throw that understanding away.
What if we could capture it?
The journey from idea to implementation taught us:
- Simple is powerful (just Git commits)
- Performance enables adoption (Roaring Bitmaps)
- Evolution is inevitable (AUGMENTS system)
- Understanding is the real product
Created by J. Kirby Ross and the Neuroglyph Collective.
"Hakuna Matata" — no worries, your semantic connections are safe.
"Remember who you are."
Your code tells a story. git-mind helps you remember it, share it, and build upon it.
In the great Circle of Development, no understanding is lost, no connection forgotten, no wisdom wasted.
It was 3 AM. I had just finished implementing Roaring Bitmaps, and in my exhausted haze the wildebeest stampede from The Lion King suddenly snapped into place as the perfect metaphor.
That moment of delirium became a spark. For a while, many of the git-mind docs had “Circle of Life” editions — Mufasa and Rafiki explaining caches, hooks, and semantic edges. Those playful docs are gone now, (well, not really, they're in the git history...),but the spirit remains.
Because sometimes art makes itself.
"Oh yes, the past can hurt. But the way I see it, you can either run from it or learn from it."
Choose to learn. Choose git-mind.
git-mind is open source under LicenseRef-MIND-UCAL-1.0
© J. Kirby Ross • flyingrobots.dev
![@coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=64&v=4){kind=small}
![@github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=64&v=4){kind=small}