From b3730d871b6246e937e459b99ddf10e8688d3eb0 Mon Sep 17 00:00:00 2001 From: jared Date: Fri, 5 Jun 2026 16:56:40 -0400 Subject: [PATCH] Add user-facing documentation for cc-os memory system Introduces README.md as the main entry point and docs/USER-GUIDE.md to guide users through the memory system design and build plan. Co-Authored-By: Claude Sonnet 4.6 --- README.md | 41 ++++++++++ docs/USER-GUIDE.md | 194 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 235 insertions(+) create mode 100644 README.md create mode 100644 docs/USER-GUIDE.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..6af6625 --- /dev/null +++ b/README.md @@ -0,0 +1,41 @@ +# cc-os — Cross-Project Memory for Claude Code + +A personal memory system for Claude Code, designed for a multi-client freelancer. +The system captures knowledge across projects and surfaces it automatically at the +start of each Claude Code session. + +## Status + +The memory plugin is **live and working.** Design documentation lives in `docs/`. +Episodic memory (memsearch) is not yet built — only semantic/knowledge memory via +Graphify is active. + +## What it does for you + +- **Injects vault context at session start** — Claude sees your SecondBrain graph + summary, your conventions, and today's journal path before you type the first message. +- **Surfaces project structure on demand** — run one command to build a graph of any + project; Claude can then query it for patterns, architecture, and conventions. +- **Remembers conventions automatically** — `memory-write` stores evergreen knowledge + (coding patterns, client rules, recurring decisions) in the correct vault location + with proper tags. +- **Stays fresh without a daemon** — the vault graph rebuilds in the background when + stale; vault writes immediately invalidate the timestamp so the next session picks + up changes. +- **Keeps project repos clean** — all indexes are build artifacts (`graphify-out/`); + nothing is committed to project repos. + +## User guide + +See **[docs/USER-GUIDE.md](docs/USER-GUIDE.md)** for setup, onboarding new projects, +using the skills, and known limitations. + +## Directory layout + +| Path | Contents | +|------|----------| +| `docs/memory-system/` | Architecture, ADRs, build plan, Graphify evaluation | +| `docs/graphify/` | Verified Graphify command handbook | +| `docs/USER-GUIDE.md` | Practical usage guide | +| `openspec/` | Spec-driven change management (changes, specs) | +| `graphify-interview`, `memory-systems-compared060326` | Raw source transcripts (do not cite as fact) | diff --git a/docs/USER-GUIDE.md b/docs/USER-GUIDE.md new file mode 100644 index 0000000..904a72c --- /dev/null +++ b/docs/USER-GUIDE.md @@ -0,0 +1,194 @@ +# Memory Plugin — User Guide + +_Last updated: 2026-06-05_ + +--- + +## 1. What you get automatically + +Every Claude Code session, three hooks fire without any action on your part: + +| Hook | What it does | +|------|-------------| +| `SessionStart` | Rebuilds vault graph in background if >7 days stale | +| `UserPromptSubmit` (first message only) | Injects vault context into Claude's context window | +| `PostToolUse` (Write/Edit on vault files) | Invalidates rebuild stamp so next session picks up changes | + +**What Claude sees at the start of every session:** + +- Vault graph map: top 50 lines of `~/Documents/SecondBrain/graphify-out/GRAPH_REPORT.md` + (graph summary + community hub list) +- Conventions: result of `graphify query "convention"` against the vault +- Journal: path to today's journal file +- Project graph: path to `/graphify-out/graph.json` if it exists (path only — + use `memory-query` to actually query it) + +Claude does not need to be told about your vault or conventions — they are already in context. + +--- + +## 2. Onboarding a new project + +Run these three commands once per project, from the project root. + +**Step 1 — Extract the graph:** + +```bash +graphify extract . --backend ollama --model qwen2.5-coder:7b +``` + +You must pass `--backend ollama`. Without it, graphify auto-selects Gemini because +`GEMINI_API_KEY` is set in your environment, which costs money and uses the wrong model. + +**Step 2 — Generate the report:** + +```bash +graphify cluster-only +``` + +This produces `graphify-out/GRAPH_REPORT.md` with named communities. Claude uses this +file to understand project structure. + +**Step 3 — Add to .gitignore:** + +```bash +echo "graphify-out/" >> .gitignore +``` + +`graphify-out/` is a build artifact. Do not commit it. + +After these steps, the next Claude Code session in that project will automatically inject +the project graph path into context. + +--- + +## 3. Updating a project graph + +Project graphs are **not updated automatically** — run these manually when the project +has evolved significantly. + +**Incremental update** (cheaper; skips unchanged files): + +```bash +graphify update . +``` + +**Full rebuild** (after significant structural changes): + +```bash +graphify extract . --backend ollama --model qwen2.5-coder:7b --force +``` + +After either command, re-run `graphify cluster-only ` to refresh the report. + +A good rule of thumb: update after adding a major new module, refactoring a core abstraction, +or onboarding a new team member who needs current structure. + +--- + +## 4. Using the skills + +**`memory-query` — query vault or project graph** + +``` +/memory-query what are the conventions for naming hooks? +/memory-query --graph /path/to/project/graphify-out/graph.json how is auth structured? +``` + +Use `memory-query` any time you want Claude to explicitly search memory rather than relying +on what was injected at session start. Required for project graph queries — the session start +injection gives Claude the path but not the content. + +**`memory-write` — write evergreen knowledge to vault** + +``` +/memory-write write a note about the convention we just decided: all hooks must be idempotent +``` + +Claude will produce the note with correct frontmatter (summary, scope, type, facet tags) and +ask you to confirm before writing. Never write vault notes by hand if you can avoid it — +getting frontmatter wrong breaks tag queries. + +**`memory-reorganize` — restructure the vault** + +``` +/memory-reorganize the convention notes are scattered, suggest a hub structure +``` + +This skill operates in **plan-mode only** — it will propose a reorganization and stop. You +must approve and direct execution. It will not move or rename files without explicit confirmation. + +--- + +## 5. Writing vault notes + +When writing notes manually or reviewing `memory-write` output, the frontmatter must include: + +```yaml +--- +summary: one-line router hint (used by graphify query and grep fallback) +tags: + - scope/global # global (applies everywhere) or scope/project (project-specific) + - type/procedure # one of: procedure, reference, log, hub, concept, decision + - client/hyperthrive # at least one facet tag (see below) +--- +``` + +**Required facet tags** — use at least one from any of these namespaces: + +| Namespace | Examples | +|-----------|---------| +| `client/` | `client/hyperthrive`, `client/acme` | +| `project/` | `project/cc-os`, `project/api-v2` | +| `domain/` | `domain/auth`, `domain/billing` | +| `tool/` | `tool/graphify`, `tool/rails` | +| `convention/` | `convention/naming`, `convention/git` | + +**The evergreen rule:** vault notes should capture knowledge that is true across sessions and +projects — decisions, patterns, conventions, reference facts. Ephemeral session notes belong +in the journal, not the vault. + +Hub notes (type/hub) tie a domain together with wikilinks. If you find a cluster of notes +that share a theme but have no hub, create one — Graphify does not create hub nodes +automatically (see Known limitations). + +--- + +## 6. Vault graph auto-refresh + +You do not need to manage vault graph freshness manually. + +- **At session start:** if the vault graph is >7 days stale, `SessionStart` triggers a + background rebuild. No output is shown; it runs quietly. +- **After vault writes:** `PostToolUse` fires on every Write/Edit to a vault file and + immediately invalidates the rebuild stamp. The next session start will trigger a rebuild, + ensuring changes made in one session are visible in the next. + +The vault graph lives at `~/Documents/SecondBrain/graphify-out/`. It is a build artifact — +do not commit it to the SecondBrain vault's git repo if you track one. + +--- + +## 7. Known limitations + +**Facet tags do not create graph edges.** +Tags like `tool/graphify` or `client/hyperthrive` appear in frontmatter but Graphify does +not convert them into graph edges. Hub notes and wikilinks are the only way to create +connections in the graph — and they must be author-provided. This is documented in ADR-014 +(`docs/memory-system/03-architecture-decisions.md`). Consequence: if you are relying on +tag-based clustering in Graphify, it will not work; use hub notes and explicit wikilinks instead. + +**Project graph injection is path-only.** +At session start, Claude receives the path to `/graphify-out/graph.json` — not +the content. To actually query the project graph, invoke `memory-query` with `--graph `. +Claude will not automatically read the project graph without being asked. + +**memsearch (episodic memory) is not built yet.** +The design calls for a second memory tier — episodic memory of what happened across sessions, +stored in Milvus Lite. This does not exist. Only semantic/knowledge memory via Graphify is +live. Session journals (written manually) are the current substitute. + +**Vault graph rebuild is fire-and-forget.** +The `SessionStart` rebuild runs in the background with no progress indicator. If the rebuild +fails silently (e.g., Ollama is not running), the stale graph continues to be used. Check +`~/Documents/SecondBrain/graphify-out/` timestamps if context seems outdated.