connectome-fs

Modern graph-based flat filesystem prototype: GUID-addressed nodes, multi-name tokens, hierarchy as a navigation view, typed associations, context filters, and sharded search.

Explore the docs »

Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Changelog
3. Tutorial: quickstart
4. How-to
5. Explanation
6. Reference
7. Out of scope (v0)
8. Website
9. Contributing
10. License
11. Contact

About The Project

Modern graph-based flat filesystem: GUID-addressed nodes, multi-name tokens, hierarchy as a navigation view, typed associations, context filters, and sharded search.

Hierarchy is an entry point into the connectome, not the source of truth. Associations and multi-names carry relationships that trees alone cannot.

(back to top)

Built With

• Core —
  • 
• Site —
• Manual —

(back to top)

Changelog

See CHANGELOG.adoc and changelog-details/.

(back to top)

Tutorial: quickstart

cargo build -p connectome-cli
cargo run -p connectome-cli -- --db demo.db demo
cargo run -p connectome-cli -- --db demo.db query "token:basename=pcss"
cargo run -p connectome-cli -- --db demo.db search pcss --shard user

cfs demo seeds the vendor-filename problem: same basename pcss, versions 1.0.0 and 1.2.3, plus system noise that default search hides.

(back to top)

How-to

Multi-names

cfs --db connectome.db add --kind file --name pcss.zip
# note the printed GUID, then:
cfs --db connectome.db name <guid> --role basename --value pcss
cfs --db connectome.db name <guid> --role version --value 1.2.3
cfs --db connectome.db ls --sort version

Contexts and hierarchy

cfs --db connectome.db add --kind category --name Downloads --category Downloads --actor user
cfs --db connectome.db link <file-guid> <downloads-guid> --kind member-of
cfs --db connectome.db ls --parent <downloads-guid> --sort basename --actor user

Queries and shards

See query grammar. Default search shard is user-authored.

cfs --db connectome.db query "shard:user-authored token:basename=pcss"
cfs --db connectome.db search pcss --shard all

(back to top)

Explanation

• Connectome model
• Source Google Docs map
• Language bindings and access targets
• SolidStart + Antora

(back to top)

Reference

• CLI: cfs init|add|name|link|ls|query|search|demo
• Query grammar
• Library crate: connectome-core (SQLite store, sort axes, SearchShard trait)

(back to top)

Out of scope (v0)

Kernel mount (WinFsp/FUSE), DHT/IPFS mesh, content-block dedup, embedding RAG backends (stubbed via RagShardStub).

(back to top)

Website

Marketing/news site is SolidStart under site/ (static). The /docs route is an onboarding gate; Antora publishes under /manual/ from AsciiDoc in docs/modules/. CI: .github/workflows/pages.yml → GitHub Pages at https://amdphreak.github.io/connectome-fs/.

# from repo root
antora antora-playbook.yml
cd site
pnpm install
pnpm build

Enable Settings → Pages → Source: GitHub Actions once on the repo.

(back to top)

Contributing

Contributions are welcome. Open an issue to discuss larger changes before submitting a pull request.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Top contributors

For per-person profile links, prefer all-contributors.

(back to top)

License

MIT — see LICENSE.

(back to top)

Contact

Ryan Johnson — @amdphreak

Project Link: https://github.com/AMDphreak/connectome-fs

Site: https://amdphreak.github.io/connectome-fs/

Blog: https://ryanjohnson.dev

(back to top)