tony/HCFS

Files

Claude Code 8f19eaab25 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>

2025-07-29 12:13:16 +10:00

2.8 KiB

Raw Blame History

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.

2.8 KiB Raw Blame History