HCFS - Hierarchical Context File System

Context-Aware Hierarchical Context File System (HCFS): Unifying file system paths with context blobs for agentic AI cognition

Overview

HCFS is a virtual filesystem layer that maps hierarchical paths to context blobs, enabling agentic AI systems to navigate and share context in a structured, hierarchical manner. It combines the intuitive nature of file system navigation with semantic context storage and retrieval.

Key Features

• Virtual Filesystem Layer: Standard POSIX-style directory navigation backed by context blobs
• Context Database Backend: Versioned context storage with hierarchical inheritance
• Semantic Indexing: Embeddings and BM25 hybrid ranking for context relevance
• Agent APIs: Syscall-style APIs for context navigation, retrieval, and publishing
• Decentralized Context Sharing: Agents can publish/subscribe to context updates by path

Quick Start

This project is currently in the planning and research phase. See PROJECT_PLAN.md for detailed architecture and implementation timeline.

Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  Agent APIs     │    │ Virtual FS      │    │ Context DB      │
│                 │    │ Layer (FUSE)    │    │ Backend         │
│ • context_cd()  │◄──►│                 │◄──►│                 │
│ • context_get() │    │ /project/       │    │ • Blob storage  │
│ • context_push()│    │ /project/src/   │    │ • Versioning    │
│ • context_list()│    │ /project/docs/  │    │ • Embeddings    │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Development Phases

• Phase 0: Research & Design (2 weeks)
• Phase 1: Prototype FS layer (4 weeks)
• Phase 2: Backend DB & storage (4 weeks)
• Phase 3: Embedding & retrieval integration (3 weeks)
• Phase 4: API/Syscall layer scripting (3 weeks)
• Phase 5: Agent integration & simulation (3 weeks)
• Phase 6: Evaluation & refinement (2 weeks)
• Phase 7: Write-up & publication (2 weeks)

Contributing

This project is in early development. See PROJECT_PLAN.md for detailed specifications and implementation roadmap.

License

MIT License - see LICENSE for details.

Research Context

HCFS builds upon research in semantic file systems, LLM-driven semantic filesystems (LSFS), path-structure embeddings, and context modeling frameworks. See the literature review section in PROJECT_PLAN.md for full references.