From e6d925df29928ecc2910c9ecb28eca6ac9cc62e1 Mon Sep 17 00:00:00 2001 From: jared Date: Tue, 9 Jun 2026 13:38:10 -0400 Subject: [PATCH] Clarify memsearch spec: install-first, audit-defaults, deviate only if needed Co-Authored-By: Claude Sonnet 4.6 --- .../2026-06-09-memsearch-episodic-layer-design.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/superpowers/specs/2026-06-09-memsearch-episodic-layer-design.md b/docs/superpowers/specs/2026-06-09-memsearch-episodic-layer-design.md index 00d939b..dc1b6e7 100644 --- a/docs/superpowers/specs/2026-06-09-memsearch-episodic-layer-design.md +++ b/docs/superpowers/specs/2026-06-09-memsearch-episodic-layer-design.md @@ -7,6 +7,10 @@ _Status: Approved, pending implementation_ Add time-anchored episodic memory to the personal Claude Code memory system. Enable queries like "what was I working on last Tuesday?" or "did we discuss X recently?" across all projects. +## Guiding Principle + +Install memsearch as a standard global plugin. Audit its default behavior before adding anything custom. Every deviation from defaults requires a concrete reason observed after install — not assumed in advance. The expected outcome is a working episodic layer with zero custom code. + ## Architecture Fit The system has two memory types kept as separate systems: @@ -41,7 +45,9 @@ All other defaults are kept: ### 3. Built-in Guidance Audit -memsearch ships as a full Claude Code plugin and likely includes its own system prompt instructions telling Claude when and how to use `memsearch search`. After install, audit what it adds to Claude's context. The default outcome of this audit is **no custom skill**. Only create a `memory-search` skill if memsearch's built-in guidance fails to cover cross-project episodic queries, or if it creates ambiguity with the `memory-vault`/`memory-project` skill boundary (e.g., Claude routing knowledge questions to memsearch instead of Graphify). +memsearch ships as a full Claude Code plugin with its own system prompt instructions and tool guidance. After install, observe what it adds to Claude's context before adding anything. + +Expected outcome: no custom skill needed. A `memory-search` skill is only warranted if — after seeing the default install — memsearch's built-in guidance fails to handle cross-project episodic recall, or creates routing confusion with `memory-vault`/`memory-project`. This will be evaluated at install time. ## Data Flow @@ -77,7 +83,7 @@ The existing hook writes vault provenance (which vault notes were touched, proje - Does not replace or modify session-end.sh - Does not add custom hook code - Does not configure Milvus Server or Zilliz Cloud (Milvus Lite is correct for personal use) -- Does not integrate memsearch recall into SessionStart hook injection (deferred) +- Does not assume SessionStart hook injection is needed — evaluate after seeing what the default global install provides - Step 4 is complete when: plugin is installed, memory_dir is confirmed global, and at least one session has produced a daily memory file at `~/.memsearch/memory/YYYY-MM-DD.md`. SessionStart injection is a distinct future step. ## Installation Checklist