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 <noreply@anthropic.com>

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) |

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 `<project>/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 <project-dir>
+```
+
+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 <project-dir>` 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 `<project>/graphify-out/graph.json` — not
+the content. To actually query the project graph, invoke `memory-query` with `--graph <path>`.
+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.