Skip to content

Commit f0fa170

Browse files
committed
docs: Update README with traversal, viz, watch, confidence features
Add documentation for all new wiki capabilities: - Knowledge traversal (trace, nearby, context) - Interactive HTML knowledge map (viz) - File watcher for auto-ingest (watch) - Confidence scoring with labels - Keystone page detection in schema - URL ingestion - Updated command reference, quick start, testing guide - Updated roadmap to v0.8 (wiki advanced features) - Updated comparison table with 7 new feature rows - Updated architecture diagram
1 parent 3fd6c00 commit f0fa170

1 file changed

Lines changed: 68 additions & 35 deletions

File tree

‎README.md‎

Lines changed: 68 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77

88
Aura is a local-first daemon that gives every AI tool you use — Claude Code, Cursor, Kiro, Gemini CLI — persistent memory, claim verification, token compression, dependency scanning, and a compounding knowledge wiki. One binary. Zero cloud. Works across tools.
99

10-
**Current status: v0.7-dev** — 19 packages, 414 passing tests.
10+
**Current status: v0.9-dev** — 20 packages, ~18,000 lines of Go, 450+ passing tests.
1111

1212
---
1313

@@ -90,44 +90,50 @@ aura replay <session_id> # replay and diff
9090

9191
**Auto-capture** — Automatically extracts decisions from AI sessions ("we decided to use PostgreSQL", "going with microservices") and stores them in memory without manual effort.
9292

93-
**Knowledge wiki** — A persistent, compounding knowledge base maintained by your AI tools. Ingest sources once, and Aura builds interlinked pages — summaries, entity pages, concept pages — that get richer with every source you add and every question you ask. Export to Obsidian-compatible markdown with YAML frontmatter and `[[wikilinks]]`. Inspired by [Karpathy's LLM Wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f).
93+
**Knowledge wiki** — A persistent, compounding knowledge base maintained by your AI tools. Ingest sources once — files, URLs, or tool output — and Aura builds interlinked pages that get richer with every source you add and every question you ask. Navigate the knowledge graph, trace connections between concepts, visualize the whole map in your browser, and let Aura watch your docs folder for automatic updates. Zero LLM calls. Inspired by [Karpathy's LLM Wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f).
9494

9595
```
96-
aura wiki ingest design.md # ingest a source document
97-
# ingested: design.md (source #1)
98-
# created: design-md, architecture-overview, database-layer
96+
aura wiki ingest design.md # ingest a file
97+
aura wiki ingest https://example.com # ingest a URL (HTML → markdown)
98+
aura wiki ingest --dir ./docs # batch ingest a whole folder
9999
100-
aura wiki ingest --dir ./docs # batch ingest a whole folder
100+
aura wiki query "authentication" # search and synthesise
101+
aura wiki query "auth" --save # file the answer as a synthesis page
101102
102-
aura wiki query "authentication" # search and synthesise
103-
# found 3 page(s):
104-
# ## Authentication
105-
# JWT tokens with 24-hour expiry...
103+
aura wiki trace auth-service database # shortest path between two pages
104+
# auth-service → jwt-tokens → database (2 hops)
106105
107-
aura wiki query "auth" --save # file the answer as a synthesis page
106+
aura wiki nearby postgresql --depth 2 # neighborhood exploration
107+
# 5 page(s) near postgresql (depth 2):
108+
# redis entity 1 linked_from
109+
# database-layer concept 1 links_to
110+
# ...
108111
109-
aura wiki lint # health-check the wiki
110-
# pages: 12
111-
# sources: 5
112-
# health: 87%
113-
# orphans (2):
114-
# - old-api-notes
115-
# - unused-concept
116-
# contradictions (1):
117-
# - page-old vs page-new: uses MySQL vs uses PostgreSQL
112+
aura wiki context auth-service # full 360° view
113+
# confidence: 85% (strong)
114+
# links to (3): jwt-tokens, database, session-mgmt
115+
# linked from (2): api-gateway, user-service
116+
# backed by (2 sources): #1 design.md, #3 auth-rfc.md
118117
119-
aura wiki graph # connectivity analysis
120-
# pages: 12
121-
# edges: 34
122-
# density: 0.258
123-
# clusters: 2
118+
aura wiki viz # interactive HTML knowledge map
119+
# knowledge map: ~/.aura/wiki-map.html (42 nodes, 87 edges)
120+
# open in any browser to explore
124121
125-
aura wiki export # Obsidian-compatible markdown + YAML frontmatter
126-
# exported 12 pages to ~/.aura/wiki-export
122+
aura wiki watch ./docs # auto-ingest on file changes
123+
# [auto] meeting-notes.md → 3 created, 1 updated
127124
125+
aura wiki lint # health-check with suggestions
126+
# health: 87%
127+
# suggestions (4):
128+
# [create_page] Create "redis-caching" — referenced but missing
129+
# [split_page] "architecture" has 620 words — consider splitting
130+
# [investigate] "old-api" hasn't been updated in 30+ days
131+
132+
aura wiki schema --format claude # generate CLAUDE.md for your LLM
133+
aura wiki filter "category=entity AND link_count>3" # Dataview-style queries
134+
aura wiki export # Obsidian-compatible markdown + YAML frontmatter
135+
aura wiki graph # connectivity stats: hubs, clusters, density
128136
aura wiki feed scan.json --tool ghostdep # feed tool output into wiki
129-
# [ghostdep] 4 findings (2 high-risk), 42 files scanned
130-
# created: tool-ghostdep-scans, dep-axios, dep-lodash
131137
```
132138

133139
## Install
@@ -199,6 +205,8 @@ go build -o aura ./cmd/aura/
199205
./aura wiki query "architecture"
200206
./aura wiki ls
201207
./aura wiki lint
208+
./aura wiki viz # open wiki-map.html in browser
209+
./aura wiki schema --format claude # generate CLAUDE.md for your LLM
202210
```
203211

204212
## Testing
@@ -288,6 +296,12 @@ go build -o aura ./cmd/aura/
288296
./aura wiki query "architecture" --dir /tmp/aura-test
289297
./aura wiki ls --dir /tmp/aura-test
290298
./aura wiki lint --dir /tmp/aura-test
299+
./aura wiki trace <slug-a> <slug-b> --dir /tmp/aura-test
300+
./aura wiki nearby <slug> --dir /tmp/aura-test
301+
./aura wiki context <slug> --dir /tmp/aura-test
302+
./aura wiki viz --dir /tmp/aura-test
303+
./aura wiki schema --format claude --dir /tmp/aura-test
304+
./aura wiki filter "category=entity" --dir /tmp/aura-test
291305
./aura wiki log --dir /tmp/aura-test
292306
./aura wiki index --dir /tmp/aura-test
293307
./aura wiki sources --dir /tmp/aura-test
@@ -337,6 +351,8 @@ The core memory, MCP server, cost tracking, policy engine, doom loop detection,
337351
│ Trace Recorder │
338352
│ Model Router ─── .aura/routing.toml │
339353
│ Wiki Engine ──── knowledge base │
354+
│ Knowledge Map ── interactive HTML │
355+
│ File Watcher ─── auto-ingest │
340356
│ Multi-Agent Coordinator │
341357
└─────────────────────────────────────────┘
342358
```
@@ -395,21 +411,31 @@ aura trust --duration 15 # auto-approve for 15 minutes
395411
aura trust --path ./src/test # auto-approve writes to test dir
396412
397413
aura wiki ingest <file> # ingest a source into the wiki
414+
aura wiki ingest <url> # ingest a URL (HTML → markdown)
398415
aura wiki ingest <text> --title # ingest inline text
399416
aura wiki ingest --dir <folder> # batch ingest all files in a directory
400417
aura wiki query <terms> # search wiki and synthesise answer
401418
aura wiki query <terms> --save # search and file the answer as a wiki page
402-
aura wiki lint # health-check: orphans, stale, missing refs, contradictions
419+
aura wiki lint # health-check with actionable suggestions
403420
aura wiki ls # list all wiki pages
404421
aura wiki ls --category entity # filter by category
405422
aura wiki show <slug> # show full page content
406423
aura wiki search <query> # search pages by title/content
424+
aura wiki trace <from> <to> # shortest path between two pages
425+
aura wiki nearby <slug> # pages within N hops (--depth 2)
426+
aura wiki context <slug> # full 360° view: links, sources, confidence
427+
aura wiki viz # interactive HTML knowledge map
428+
aura wiki viz --out <file> # export map to specific file
429+
aura wiki watch <dir> # auto-ingest on file changes
430+
aura wiki schema # generate LLM schema (CLAUDE.md / AGENTS.md)
431+
aura wiki schema --format claude # target a specific LLM tool
432+
aura wiki filter <expression> # Dataview-style metadata queries
433+
aura wiki graph # connectivity stats: hubs, clusters, density
407434
aura wiki log # show wiki activity log
408435
aura wiki index # show full wiki catalog
409436
aura wiki sources # list all ingested raw sources
410-
aura wiki export # export as Obsidian-compatible markdown with YAML frontmatter
437+
aura wiki export # Obsidian-compatible markdown + YAML frontmatter
411438
aura wiki export --out <dir> # export to a specific directory
412-
aura wiki graph # connectivity stats: hubs, clusters, density
413439
aura wiki rm <slug> # delete a wiki page
414440
415441
aura wiki feed <file> --tool sqz # feed sqz compression stats into wiki
@@ -466,9 +492,10 @@ aura/
466492
- [x] v0.5 — Multi-agent shared memory
467493
- [x] v0.6 — Model router with budget control
468494
- [x] v0.7 — LLM Wiki knowledge base (ingest, query, lint, index)
469-
- [ ] v0.8 — Desktop app (Tauri)
470-
- [ ] v0.9 — Enterprise features (team sync, SSO, audit logs)
471-
- [ ] v0.10 — Browser extension (Chrome/Firefox)
495+
- [x] v0.8 — Wiki advanced features (traversal, confidence, visualization, watch, schema, URL ingest, filters, tool pipeline)
496+
- [ ] v0.9 — Desktop app (Tauri)
497+
- [ ] v0.10 — Enterprise features (team sync, SSO, audit logs)
498+
- [ ] v0.11 — Browser extension (Chrome/Firefox)
472499
- [ ] v1.0 — Plugin system and public API
473500

474501
## Tech stack
@@ -498,6 +525,12 @@ aura/
498525
| Session traces | ✅ | ❌ | ❌ | ❌ |
499526
| Auto-capture | ✅ | ❌ | ❌ | ❌ |
500527
| Knowledge wiki | ✅ | ❌ | ❌ | ❌ |
528+
| Knowledge map (HTML) | ✅ | ❌ | ❌ | ❌ |
529+
| Graph traversal | ✅ | ❌ | ❌ | ❌ |
530+
| Confidence scoring | ✅ | ❌ | ❌ | ❌ |
531+
| File watch auto-ingest | ✅ | ❌ | ❌ | ❌ |
532+
| URL ingestion | ✅ | ❌ | ❌ | ❌ |
533+
| LLM schema generator | ✅ | ❌ | ❌ | ❌ |
501534
| Single binary (Go) | ✅ | ❌ (Python) | ❌ (Python) | ✅ |
502535
| Local-first | ✅ | ✅ | ❌ | ✅ |
503536

0 commit comments

Comments
 (0)