# Memory Plugin — User Guide

_Last updated: 2026-06-08_

---

## 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:**

- Project graph: path to `<project>/graphify-out/graph.json` if one exists in the current
  project root (path only — use `memory-project` to actually query it)

The session-context hook no longer injects vault graph map, conventions, or a journal pointer.
Use `memory-vault` to query cross-project knowledge on demand.

---

## 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-vault` — query cross-project knowledge from the vault**

```
/memory-vault what are the conventions for naming hooks?
/memory-vault how does the auth pattern work across projects?
```

Use `memory-vault` any time you want Claude to explicitly search the Obsidian vault rather
than relying on what was injected at session start. Good for conventions, tool behavior,
decisions, and any evergreen knowledge that spans projects.

**`memory-project` — per-project graph lifecycle (onboard, update, remove, query)**

```
/memory-project query how is auth structured?
/memory-project onboard
/memory-project update
/memory-project remove
```

Use `memory-project` to query the current project's graph or to manage its lifecycle.
Required for project graph queries — the session start injection gives Claude the path but
not the content. `onboard` runs the full extract + cluster sequence; `update` does an
incremental refresh; `remove` drops the graph and cleans up `.gitignore`.

**`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.

Note the contrast with episodic memory: while vault notes use `client/` and `scope/` facets to
scope individual notes, memsearch episodic memory is a **single global store spanning all
clients and projects** — there is no per-client partitioning at the store level (by design).

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-project query <question>`.
Claude will not automatically read the project graph without being asked.

**memsearch (episodic memory) is live as of 2026-06-09.**
The second memory tier — episodic memory of what happened across sessions, stored in Milvus
Lite — is installed and operational. Memory is captured globally across all clients and
projects in one store (`~/.memsearch`), synced to a private self-hosted Forgejo repo
(`forgejo.swansoncloud.com/jared/memsearch`). This is the intended design: a single
commingled global store, not per-client stores. Use `/memory-recall` to search episodic memory;
use `/memory-config` to inspect configuration. See ADR-015 for the rationale and sync details.

**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.
