195 lines
6.9 KiB
Markdown
195 lines
6.9 KiB
Markdown
# 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.
|