okc 0.1.0

A local-first tool for AI agents to browse, parse, search, and reason over Open Knowledge Format (OKF) repositories
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83

---
type: Documentation
title: Roadmap
description: Phase status and known issues tracked in backlog
tags:
  - roadmap
  - planning
  - status
owner: Engineering Team
status: published
---

# Roadmap

## Phase 1 (Current) - Minimal Repository Reader
- ✅ Filesystem traversal with ignore support
- ✅ Front-matter extraction & YAML parsing
- ✅ Normalized document records
- ✅ Basic CLI output

## Phase 2 - Markdown Structure
- ✅ Heading extraction
- ✅ Internal link extraction & resolution
- ✅ Broken link detection
- ✅ Directory tree construction

## Phase 3 - Persistent Index
- ✅ SQLite schema with FTS5
- ✅ Incremental file updates
- ✅ Metadata indexes
- ✅ Deleted file handling

## Phase 4 - AI-Facing Operations
- ✅ `browse_directory`
- ✅ `get_document` / `get_section`
- ✅ `search_documents`
- ✅ `query_metadata`
- ✅ `get_links` / `get_backlinks`
- ✅ `traverse_graph`
- ✅ `validate_repository`
- ✅ MCP server transport (stdio + HTTP)

## Phase 5 - Continuous Updates
- ✅ Filesystem watcher (`notify`)
- ✅ Debounced updates
- ✅ Partial graph rebuilding
- ✅ Index health reporting

## Phase 6 - Advanced Retrieval (Future)
*Only add after measuring real retrieval failures:*

The initial measurement is recorded in
[Lexical Search Baseline v1](search-baseline-v1.md). It recommends consolidating
the production search path and addressing typo and graph-expansion failures
before deciding on embeddings.

- Fuzzy filename matching
- Trigram search
- Semantic embeddings
- Reranking
- Generated directory summaries
- PageIndex-style hierarchical reasoning
- Relationship extraction from custom metadata

## Current Status

| Phase | Status | Completion |
|-------|--------|------------|
| 1 | ✅ Done | 100% |
| 2 | ✅ Done | 100% |
| 3 | ✅ Done | 100% |
| 4 | ✅ Done | 100% |
| 5 | ✅ Done | 100% |
| 6 | 🔮 Future | 0% |

## Known Issues (Tracked in Backlog)

- **OKC-00001**: SQL injection in `query_metadata`
- **OKC-00003**: FTS5 BM25 relevance ranking
- **OKC-00007**: Link resolution edge cases
- **OKC-00008**: YAML aliases/anchors/merge keys

See `backlog/tasks/` for full task list.