# 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 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. 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`