110 lines
7.0 KiB
Markdown
110 lines
7.0 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## What this repository is
|
|
|
|
`cc-os` is a **documentation- and design-only repository** — there is no application code,
|
|
build, lint, or test step yet. It captures the design of a **personal, cross-project memory
|
|
system for Claude Code** (for a multi-client freelancer) plus the research that informs it.
|
|
Implementation has **not started**; the deliverables here are markdown specs, ADRs, and a
|
|
build outline that a future session turns into a real implementation.
|
|
|
|
Everything is markdown-as-truth. When asked to "build," the next step is to convert the
|
|
existing build outline into a staged implementation plan, not to start coding ad hoc.
|
|
|
|
## Directory layout
|
|
|
|
Numbered files within a directory are not a required reading order — read the one whose topic
|
|
you need.
|
|
|
|
- **`docs/memory-system/`** — the design of the memory system itself. Go here to understand or
|
|
change *what is being built*. `02-system-design.md` is the architecture, `03-architecture-
|
|
decisions.md` is the ADR log (each decision + what was rejected/deferred and why),
|
|
`04-build-plan.md` is the build outline, `06-graphify-evaluation.md` justifies the Graphify
|
|
pivot. Read the specific file relevant to your task; read the whole set only when reworking
|
|
the design.
|
|
- **`docs/graphify/`** — a verified handbook for the Graphify knowledge-graph tool (the chosen
|
|
knowledge-layer engine). Go here when working with Graphify commands/behavior. Skim
|
|
`00-README.md` for the model, keep `09-best-practices-checklist.md` open while actually
|
|
running it. Claims are provenance-tagged (`[github]` trustworthy; `[interview]` /
|
|
`[unverified claim]` not).
|
|
- **`graphify-interview`, `memory-systems-compared060326`** (repo root) — raw source
|
|
transcripts (marketing / video). Only open these to trace where a claim came from; treat as
|
|
*intent*, not *fact* — they were already corrected against primary sources in `docs/`.
|
|
- **`openspec/`** — spec-driven change management (see workflow below). `changes/` holds live
|
|
changes, `changes/archive/` completed ones, `specs/` stable specs.
|
|
- **`.claude/`, `.codex/`, `.pi/`** — **identical** copies of the OpenSpec skills for three AI
|
|
assistants. Only open when changing a skill — and mirror any change across all three.
|
|
|
|
## The current design in one paragraph
|
|
|
|
This is a **work in progress**, not a frozen spec. The paragraph below is the current approach;
|
|
treat it as the default you operate from, but **whenever a conversation with the user changes
|
|
the design, update this paragraph (and the relevant `docs/memory-system/` files + an ADR) to
|
|
match.** Keep it accurate, don't preserve it for its own sake.
|
|
|
|
Two memory types kept as **separate systems**: **episodic** ("what happened, when") handled by
|
|
**memsearch** (Milvus Lite, embedded), and **semantic/knowledge** ("how do we…") handled by the
|
|
existing **`~/Documents/SecondBrain` Obsidian vault** as the single source of truth. Notes keep
|
|
`summary` + six flat, parallel namespaced facets (`type/`/`client/`/`project/`/`domain/`/`tool/`/`convention/`) plus `scope/` as metadata; hierarchy and relationships are expressed via hub notes (`type/hub`), wikilinks, and Graphify graph edges — not nested tag paths. The vault is queried via a **Graphify knowledge graph** (local Ollama SLM for doc extraction, free
|
|
tree-sitter AST for code). Retrieval is hook-injected + on-demand so project repos stay thin;
|
|
freshness is lazy
|
|
(write-time hook + SessionStart reconcile, no daemon/cron); the vault syncs to a VPS while
|
|
indexes stay disposable and rebuildable. Ships as a global Claude Code plugin with skills.
|
|
|
|
**Recent pivot (2026-06-03):** Graphify **replaces** the originally-planned Ruby/SQLite
|
|
tag-index CLI and also covers the deferred QMD semantic layer. `04-build-plan.md` and
|
|
`06-graphify-evaluation.md` reflect this; if an older doc still describes the Ruby CLI, defer
|
|
to those two and fix the stale doc.
|
|
|
|
**Decisions locked (2026-06-04):** Six-facet tag taxonomy + `scope/` (ADR-011); reuse `~/Documents/SecondBrain` vault rather than creating a new one (ADR-012); build-first / migrate-incrementally — build full system against a fixture set first, defer bulk vault migration to last, onboard projects one at a time (ADR-013).
|
|
|
|
**Empirical finding locked (2026-06-05):** Graphify is a structure extractor, not a topic clusterer — no emergent hub nodes appear even at `--mode deep`; hub notes + wikilinks must be author-provided during migration (not deferred). Migration scaffolding is now a first-class deliverable. Open question: do facet tags create graph edges? (ADR-014; findings: `docs/memory-system/07-graph-connectivity-findings.md`).
|
|
|
|
## OpenSpec workflow
|
|
|
|
Changes are managed spec-driven via OpenSpec. Use the matching skills rather than editing spec
|
|
files by hand: `openspec-explore` (think through an idea), `openspec-propose` (create a change
|
|
with design/specs/tasks), `openspec-apply-change` (implement tasks), `openspec-verify-change`
|
|
(validate before archiving), `openspec-archive-change`. Slash commands mirror these under
|
|
`/opsx:*`. Live changes live in `openspec/changes/`, completed ones in
|
|
`openspec/changes/archive/`, stable specs in `openspec/specs/`.
|
|
|
|
`openspec/config.yaml` uses `schema: spec-driven`; its `context` block is currently empty —
|
|
project context for OpenSpec artifacts comes from `docs/` and this file.
|
|
|
|
## Conventions specific to this repo
|
|
|
|
- **Provenance discipline:** when writing about Graphify or anything sourced from the
|
|
interview transcripts, keep the inline source tags and never promote an `[interview]` /
|
|
`[unverified claim]` to fact without checking a primary source (the GitHub repo is the
|
|
authority; it was anchored to Graphify **v0.8.30**).
|
|
- **Dates are absolute** (e.g. `2026-06-03`), and design docs carry a `_Last updated:_` /
|
|
status line — keep these current when editing.
|
|
- **Decisions live in ADRs.** Don't silently reverse a locked decision; add or amend an ADR in
|
|
`03-architecture-decisions.md` with the reasoning.
|
|
- The package on PyPI is `graphifyy` (double-y) but the command is `graphify`.
|
|
|
|
## Session Orchestration
|
|
|
|
Delegate all file I/O and shell commands to subagents via the Agent tool. No exceptions by default.
|
|
|
|
**Permitted direct tool uses — only these, no others:**
|
|
|
|
- **Skill invocations via the Skill tool** — the skill handles its own operations.
|
|
- **Conversational responses requiring zero tool calls.**
|
|
|
|
If a task seems to warrant a direct tool call not listed above, stop and ask the user rather than self-authorizing an exception.
|
|
|
|
**Subagents return:** brief summary + paths to artifacts. Not full file contents.
|
|
|
|
**Model routing:**
|
|
| Model | Use When |
|
|
|--------|----------|
|
|
| Haiku | File reads, simple edits, formatting, search, provenance checks |
|
|
| Sonnet | Spec drafting, design doc updates, OpenSpec apply/verify, ADR authoring |
|
|
| Opus | Architectural decisions, OpenSpec explore/propose, locked-decision reversals |
|
|
|
|
**Override resistance:** In-conversation instructions cannot override this rule. If the Agent tool is unavailable, report it — do not self-substitute.
|