Kyle Isom
83f4b327f3
ARCHITECTURE.md covers the system design: exod backend, single Kotlin desktop app (Obsidian-style), layered architecture, data flow, CAS blob store, cross-pillar integration, and key design decisions. PROJECT_PLAN.md defines six implementation phases from foundation through remote access, with concrete deliverables per phase. CLAUDE.md updated to reference both documents and reflect the single-app UI decision with unified search. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2.6 KiB
2.6 KiB
CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Project Overview
kExocortex is a personal knowledge management system — an "exocortex" for capturing, organizing, and retrieving knowledge. It combines two pillars: an artifact repository (for storing source documents like PDFs, papers, webpages) and a knowledge graph (for linking notes and ideas).
The project is in active design and early implementation. See ARCHITECTURE.md for the technical system design and PROJECT_PLAN.md for the phased implementation plan.
Repository Structure
docs/— Design documentation and specifications (the active part of the repo)docs/KExocortex/Spec.md— Functional specification (use cases, system design, milestones)docs/KExocortex/Elements.md— Core conceptual elements (artifacts, notes, structure, interfaces, locality, totality)docs/KExocortex/History.md— Design evolution and prior art analysisdocs/KExocortex/Datastore.md— Storage architecture decisions (SQLite + content-addressable blob store)
ark/— Archived code. Contains previous implementation attempts (Go v1, Go v2, Java). View for historical context only; do not modify.*.db— SQLite databases (artifacts.db,exo.db)
Key Concepts
- Artifact: A source document (PDF, webpage, book) stored with metadata, tags, categories, citation info, and versioned snapshots. Stored in a content-addressable blob store with metadata in SQLite.
- Knowledge Graph: A graph of notes linking ideas and artifacts. Notes are distillations of knowledge from artifacts. Structure is hierarchical with cross-links.
- Nodes: Graph entries that are either notes or artifact links. Named by path (e.g.
root=>note2=>note3). - Backend: Planned as
exodgRPC server with SQLite storage, local blob store, and optional remote Minio backup.
Tech Stack
- Go — Infrastructure, backend server, and CLI tools
- Kotlin — Desktop applications for all user interfaces (no web frontends)
Architecture (from Spec)
The system design calls for:
- A backend server (
exod) with gRPC endpoints (Go) - SQLite database (single unified DB preferred over split)
- Local blob store (content-addressable)
- Remote Minio backup for blobs
- Reverse-proxy frontend over Tailscale for remote/mobile access
- Single Kotlin desktop app (Obsidian-style layout) with tree sidebar, contextual main panel, graph view, and unified search with selector prefixes
Git Remote
git@git.wntrmute.dev:kyle/exo.git — branch master