6e8f0db6c0
- Add dialogue prompt file writing for audit/debugging - Update README install instructions - Add new RFCs (0053, 0055-0059, 0062) - Add recorded dialogues and expert pools - Add ADR 0018 dynamodb-portable-schema - Update TODO with hook configuration notes Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
77 lines
2.8 KiB
Markdown
77 lines
2.8 KiB
Markdown
# UKFS Specification Review - Background
|
|
|
|
## Document Under Review
|
|
|
|
**Universal Knowledge Filesystem (UKFS) v0.1.0** - A hierarchical directory-based architecture for organizing arbitrary knowledge in a format optimized for autonomous agent navigation.
|
|
|
|
## Core Innovation
|
|
|
|
Unlike RAG (probabilistic embedding similarity) or Tool-Based Retrieval (query languages), UKFS enables **deterministic semantic path traversal** - agents reason about knowledge location rather than search for it.
|
|
|
|
## Current Specification
|
|
|
|
### Root Directory Structure
|
|
```
|
|
/{root}/
|
|
├── .spec/ # UKFS specification metadata
|
|
├── e/ # ENTITIES (nouns)
|
|
├── r/ # RELATIONS (edges)
|
|
├── t/ # TIMELINE (events)
|
|
├── s/ # STATE (current snapshots)
|
|
├── p/ # PROCEDURES (how-to)
|
|
└── q/ # QUERIES (cached Q&A)
|
|
```
|
|
|
|
### Entity Types (/e/)
|
|
- person, org, place, concept, project, asset, task, word
|
|
|
|
### Relation Convention
|
|
`{subject}+{object}.yaml` in `/r/{relation-type}/`
|
|
|
|
### Design Principles
|
|
1. Path as identifier (human-readable, greppable)
|
|
2. No UUIDs in paths (speakable, memorable)
|
|
3. Type as namespace (disambiguation through hierarchy)
|
|
4. English structure, universal content
|
|
5. Relations as first-class files
|
|
6. State separation (current vs timeless)
|
|
|
|
### Agent Navigation Algorithm (8 steps)
|
|
1. Parse query for entity references and intent
|
|
2. Identify relevant entity types
|
|
3. Resolve entity paths: /e/{type}/{slug}/
|
|
4. Find relations: /r/{relation-type}/*{entity}*.yaml
|
|
5. Check state if "current": /s/
|
|
6. Check timeline if temporal: /t/
|
|
7. Check procedures if "how to": /p/
|
|
8. Synthesize response
|
|
|
|
## Key Questions for Deliberation
|
|
|
|
1. **Naming Convention**: Single-character (e/, r/, t/, s/, p/, q/) vs full names (entities/, relations/...)
|
|
- Trade-offs: brevity vs discoverability vs agent navigation efficiency
|
|
|
|
2. **Entity Type Coverage**: Are person, org, place, concept, project, asset, task, word sufficient?
|
|
|
|
3. **Relation Modeling**: Is {subject}+{object}.yaml adequate? What about:
|
|
- N-ary relations (3+ participants)
|
|
- Relation attributes
|
|
- Bidirectional relations
|
|
|
|
4. **State vs Timeline**: Is /s/ vs /t/ separation clear? Edge cases?
|
|
|
|
5. **Query Caching (/q/)**: Staleness concerns? Invalidation strategy?
|
|
|
|
6. **Scalability**: Millions of entities? Sharding strategies?
|
|
|
|
7. **Agent Navigation**: Is the 8-step algorithm complete? Disambiguation? Fallbacks?
|
|
|
|
8. **Git Integration**: Merge conflicts? Concurrent edits?
|
|
|
|
9. **Security/Privacy**: Access control? Encryption?
|
|
|
|
10. **Missing Concepts**: What fundamental categories are absent?
|
|
|
|
## Success Criteria
|
|
|
|
The dialogue should produce concrete, actionable improvements to the UKFS specification that maintain its core philosophy (deterministic semantic navigation) while addressing practical concerns.
|