jared
/
cc-os
1
0
Fork 0
Code Issues 17 Pull Requests Packages Projects Releases Wiki Activity
cc-os/CLAUDE.md

10 KiB
Raw Blame History

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-09): The global Claude Code plugin is live (~/.claude/plugins/memory/). Steps 1, 2a, 2b, 3, and 6 of the build plan are complete (including the memory-project skill, previously TODO under Step 6/Part D). Step 1 completed 2026-06-09: vault-conventions.md exists, all 6 fixture notes seeded, and 14 Graphify handbook + memory-system design notes migrated to the vault as migration scaffolding. Step 4 (memsearch) completed 2026-06-09: plugin installed via marketplace, MEMSEARCH_DIR set global (~/.memsearch), Stop hook verified producing daily memory files, search confirmed working. Step 5a (memsearch episodic git sync) completed 2026-06-09: dedicated private Forgejo repo (forgejo.swansoncloud.com/jared/memsearch), whitelist .gitignore (memory/*.md only), auto-commit+push via cc-os session-end.sh hook (ADR-015). Step 5b (Obsidian vault → VPS sync) remains. See docs/memory-system/04-build-plan.md for full step status.

Decision (2026-06-09): Single global memsearch store for ALL clients — cross-client commingling is the accepted, intended design (ADR-015 resolved). One private Forgejo repo (forgejo.swansoncloud.com/jared/memsearch), not per-client repos. Forward direction: minimize/eliminate dedicated per-client working directories; work projects locally or use a single general clients/ dir for non-local client work — memory is captured globally regardless of cwd. No clients/ directory structure designed yet; open item.

Implemented Components

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

  • Hooks: hooks/ — session-start.sh, session-context.sh (project graph path only), post-tool-use-write.sh, session-end.sh
  • Skills: skills/ — memory-vault, memory-write, memory-reorganize, memory-project
  • 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/vault-conventions.md — frontmatter contract + tag taxonomy (canonical name decided 2026-06-09; formerly referred to as CONVENTIONS.md)

memsearch — v0.4.6 via Claude Code plugin marketplace (memsearch@memsearch-plugins)

  • Hooks: Stop, SessionStart, UserPromptSubmit, SessionEnd (ship with plugin)
  • Memory store: ~/.memsearch/memory/YYYY-MM-DD.md daily files (global, cross-project, all clients — one store by design)
  • Index: ~/.memsearch/milvus.db (Milvus Lite, local); embeddings via ONNX bge-m3
  • Config: MEMSEARCH_DIR=~/.memsearch in ~/.zshrc for global scope
  • Skills: /memory-recall, /memory-config (ship with plugin)
  • Git sync: ~/.memsearch is a dedicated private Forgejo repo (forgejo.swansoncloud.com/jared/memsearch); whitelist .gitignore commits only memory/*.md (excludes rebuildable milvus.db, model, config); auto-commit+push wired into the cc-os memory plugin's own session-end.sh hook (see ADR-015)

Not yet implemented: Obsidian vault → VPS sync (Step 5b). Memsearch episodic git sync is done (Step 5a, 2026-06-09).

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.