exo/CLAUDE.md

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. The design docs in docs/ are the primary working material.

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 analysis
  • docs/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 exod gRPC 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:

1. A backend server (exod) with gRPC endpoints (Go)
2. SQLite database (single unified DB preferred over split)
3. Local blob store (content-addressable)
4. Remote Minio backup for blobs
5. Reverse-proxy frontend over Tailscale for remote/mobile access
6. Kotlin desktop apps covering four UI facets: query, exploration, presentation, and update

Git Remote

git@git.wntrmute.dev:kyle/exo.git — branch master