Initial HCFS project scaffold

🚀 Generated with Claude Code

- Project plan and architecture documentation
- Python package structure with core modules
- API design and basic usage examples
- Development environment configuration
- Literature review and research foundation

Ready for Phase 1 implementation.

Co-Authored-By: Claude <noreply@anthropic.com>

README.md

@@ -0,0 +1,55 @@
+# 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.