jared
/
cc-os
1
0
Fork 0
Code Issues 18 Pull Requests Packages Projects Releases Wiki Activity
cc-os/openspec/changes/archive/2026-06-05-add-memory-plugin/proposal.md

4.4 KiB
Raw Blame History

Why

The memory system's knowledge graph (vault + Graphify) and episodic layer (memsearch) are built and validated, but Claude Code has no runtime awareness of them — hooks are not registered, skills do not exist, and there is no mechanism by which a session injects vault context or records what was touched. This change delivers the global Claude Code plugin that makes the system live: hooks that inject knowledge automatically and update the graph on writes, plus three on-demand skills that teach Claude when and how to read from and write to the vault.

What Changes

  • New: ~/.claude/plugins/memory/ global plugin — installs hooks (SessionStart, PostToolUse, SessionEnd) and the three skills at the user level; all projects inherit without per-project setup.
  • New: SessionStart hook — staleness check (rebuild stamp age vs. threshold) + forced rebuild if stale; injects vault god-nodes, current-project convention/* summaries, episodic journal pointer, and project graph path if a project graph exists.
  • New: PostToolUse hook (Write/Edit on vault .md) — runs graphify update --file <path> to merge changed notes into the vault graph event-driven, no polling.
  • New: SessionEnd hook — appends a dated episodic journal note with pointers to vault notes touched in the session.
  • New: memory-query skill — when/how to use graphify query / path / explain vs. memsearch; god-node discipline; --budget / --dfs usage; cross-client lookups via --graph; tag-scoped retrieval treated as a separate path from graph traversal (open question per ADR-014).
  • New: memory-write skill — when knowledge is evergreen vs. project-ephemeral; required frontmatter contract (summary + scope/); vault-not-repo rule.
  • New: memory-reorganize skill — plan-mode consolidation/promotion procedure; when to trigger --force rebuild; human-review guardrails.
  • New: plugin config block — vault path, Graphify output dir, Ollama model name, num_ctx, rebuild-stale threshold (days), env vars (OLLAMA_FLASH_ATTENTION, GRAPHIFY_OLLAMA_NUM_CTX, GRAPHIFY_OLLAMA_KEEP_ALIVE).

Out of scope / prerequisite (not tasks here): Vault migration scaffolding — authoring hub notes + wikilinks — is a prerequisite for useful retrieval (ADR-014: Graphify is a structure extractor, not a topic clusterer; connectivity comes from authored hub notes + wikilinks). This change assumes that scaffolding either exists for the fixture set or will be done as a parallel prerequisite.

Capabilities

New Capabilities

  • memory-plugin-hooks: The three lifecycle hooks (SessionStart / PostToolUse / SessionEnd) that make graph freshness and context injection automatic. Covers the shell wrapper logic, staleness check, stamp file, graphify update --file invocation, and journal note append.
  • memory-plugin-skills: The three skills (memory-query, memory-write, memory-reorganize) that teach Claude the behavioral conventions for the memory system. Covers query-pattern guidance, frontmatter contract, write-path rules, and reorganize procedure.

Modified Capabilities

Impact

  • New global plugin at ~/.claude/plugins/memory/ (or equivalent user-level plugin install path); no per-project files created.
  • Dependencies: Graphify (graphifyy, anchored to v0.8.31), Ollama with qwen2.5-coder:7b (or the selected model from local-model-selection), memsearch plugin already installed.
  • Known fragile runtime dependency: reasoning_effort:"none" patch to Graphify's installed llm.py — lost on pip upgrade; tracked as a risk. Treat installed version as pinned until upstream resolves.
  • Env vars set in plugin config: OLLAMA_FLASH_ATTENTION=1, GRAPHIFY_OLLAMA_NUM_CTX=8192, GRAPHIFY_OLLAMA_KEEP_ALIVE=5.
  • Consumes: built vault graph (vault-graph-build), selected extraction model (local-model-selection), ADR-007 (lazy freshness), ADR-009 (global plugin), ADR-011 (six-facet taxonomy), ADR-013 (build-first/migrate-incrementally), ADR-014 (graph connectivity from authored structure).
  • Unblocks: the per-project code-graph onboarding phase (Step 2e, separate change) and bulk vault migration (Step 5, separate change).