7.9 KiB

Raw Blame History

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:

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:

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:

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

graphify update .

Full rebuild (after significant structural changes):

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:

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

7.9 KiB Raw Blame History