cc-os/CLAUDE.md

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 design + implementation repository — 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. The global memory plugin is now partially implemented; markdown specs, ADRs, and the build plan remain the source of truth for what is being built and what remains.

Everything is markdown-as-truth. When asked to "build," work from the staged tasks in docs/memory-system/04-build-plan.md, not 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).

Implementation status (2026-06-08): The global Claude Code plugin is live (~/.claude/plugins/memory/). Steps 2a, 2b, 3, and 6 of the build plan are complete. Steps 1 (vault conventions), 4 (memsearch), and 5 (sync) remain. See docs/memory-system/04-build-plan.md for full step status.

Implemented Components

Global memory plugin — ~/.claude/plugins/memory/

• Hooks: hooks/ — session-start.sh, session-context.sh, post-tool-use-write.sh, session-end.sh
• Skills: skills/ — memory-query, memory-write, memory-reorganize (memory-project-graph is TODO)
• Config: config.yaml — vault path, Ollama model (qwen25-coder-7b-16k), env vars
• Hook wiring: ~/.claude/settings.json

Graphify — v0.8.31 at /home/jared/.local/bin/graphify

• Vault graph: ~/Documents/SecondBrain/graphify-out/ — disposable, rebuilt by SessionStart hook
• Project graph: <project-root>/graphify-out/ — same pattern; gitignore it in each project repo
• Vault conventions: ~/Documents/SecondBrain/CONVENTIONS.md — frontmatter contract + tag taxonomy

Not yet implemented: vault conventions migration (Step 1), memsearch episodic layer (Step 4), VPS sync (Step 5)

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.
• Keep this file current: When a build step completes, (a) mark it done in docs/memory-system/04-build-plan.md, (b) add or update a component pointer in the Implemented Components section above, and (c) update the current design paragraph if the design changed. This file is the AI's orientation entry point — accuracy matters more than brevity.

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.