Cognitive Filesystem (CFS) is a local-first, deterministic semantic storage and retrieval system written in rust, designed to index personal documents, keep them continuously up to date, and make them searchable across devices with cryptographic verification.
It is a semantic substrate intended to be stable, inspectable, and correct before any LLM-based intelligence is layered on top.
CFS currently provides a complete end-to-end pipeline for:
- Local document ingestion
- Incremental semantic indexing
- Hybrid (lexical + vector) retrieval
- Deterministic context assembly
- Encrypted, verifiable synchronization
- 100% Local Inference on desktop and mobile
- Desktop and mobile parity
No cloud inference or external AI APIs are required.
-
Local-first All ingestion, indexing, and retrieval run locally.
-
Deterministic Identical inputs produce identical state roots, chunk IDs, and retrieval results. This is enforced via SoftFloat arithmetic and Canonical Inference.
-
Mutable but stable File changes trigger incremental updates without reindexing unrelated content.
-
Inspectable Internal state (chunks, hashes, state roots) is visible and debuggable.
CFS is defined by a rigorous set of specifications that ensure interoperability and determinism.
- CFS-001: Data Model — Canonical data types (Document, Chunk, Embedding), UUIDv5 identity generation, and Merkle tree construction.
- CFS-002: Storage Engine — Hybrid persistence using SQLite for metadata and HNSW for transient vector indices.
- CFS-003: Determinism — Mathematical rules for SoftFloat arithmetic and Canonical Inference to guarantee bit-exact synchronization.
- CFS-010: Embedding — Deterministic vector generation using quantization and provenance tracking.
- CFS-011: Indexing — Document ingestion, chunking strategies, and index maintenance.
- CFS-012: Retrieval — Hybrid search (Semantic + Lexical), RRF fusion, and Integer Dot Product scoring.
- CFS-013: Synchronization — Encrypted, blind synchronization using Merkle diffs and signatures.
- CFS-020: Intelligence Interface — strict read-only contract for LLM integration.
- CFS-021: Context Assembly — Deterministic context window construction for RAG.
- Folder selection and live ingestion
- State root and graph statistics display
- Hybrid query interface
- Chunk browser (debug surface)
- Manual sync controls
- Read-only local graph (V0)
- Encrypted state pull with Merkle-root verification
- Hybrid query support (Semantic + Lexical)
- On-device inference via
llama.cpp - "End-to-End Private" badge confirms local work
- State Verification view explains deterministic state roots
- Verified latency metrics for substrate-to-intelligence synthesis
Both apps are intentionally minimal and expose internal state rather than hiding it.
cfs-core— Canonical data models, hashing, cryptographic primitivescfs-parser— Document parsing and chunking (PDF, Markdown, Text)cfs-embeddings— Local embedding generation (CPU-only)cfs-graph— SQLite + HNSW hybrid storage enginecfs-query— Hybrid retrieval, RRF fusion, and context assemblycfs-inference-mobile— Local LLM inference engine (llama.cpp+ GGUF)cfs-sync— Merkle tree diffing, encryption, and state convergencecfs-relay-client— HTTP client for encrypted blob synchronizationcfs-desktop— Desktop-specific ingestion and watcher logiccfs-mobile— C FFI for iOS/Android integrationcfs-desktop-cli— Command-line interface for graph inspectioncfs-tests— End-to-end and cross-platform validation tests
apps/macos— macOS Tauri UI wrapperapps/ios— iOS SwiftUI application
relay/cfs-relay-server— Blind Axum-based encrypted blob storage
scripts/— Build and deployment scripts (e.g., iOS cross-compilation)test_corpus/— Curated dataset for system validation and RAG testing