# 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](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](PROJECT_PLAN.md) for detailed specifications and implementation roadmap.

## License

MIT License - see [LICENSE](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](PROJECT_PLAN.md) for full references.