cognitive-core 0.1.0 → 0.2.0

package/references/minimem/claude-plugin/README.md

@@ -0,0 +1,158 @@
+# minimem Claude Code Plugin
+
+A Claude Code plugin that provides memory capabilities via the minimem semantic search system.
+
+## Features
+
+- **MCP Server**: Provides `memory_search` tool for semantic search across memories
+- **Memory Skill**: Automatically invoked when storing or recalling information
+- **Commands**:
+  - `/minimem:remember <text>` - Store information for later
+  - `/minimem:recall <query>` - Search for stored memories
+
+## Installation
+
+### Prerequisites
+
+1. Install minimem globally:
+   ```bash
+   npm install -g minimem
+   ```
+
+2. Initialize your global memory directory:
+   ```bash
+   minimem init --global
+   ```
+
+3. Set your embedding API key:
+   ```bash
+   export OPENAI_API_KEY=your-key
+   # or
+   export GOOGLE_API_KEY=your-key
+   ```
+
+### Install the Plugin
+
+#### Option 1: Test locally during development
+
+```bash
+claude --plugin-dir /path/to/minimem/claude-plugin
+```
+
+#### Option 2: Install from a marketplace
+
+If this plugin is published to a marketplace:
+
+```
+/plugin install minimem
+```
+
+## Usage
+
+### Automatic Memory Skill
+
+The memory skill is automatically invoked when you:
+- Ask Claude to "remember" something
+- Ask Claude to "recall" or "find" previous context
+- Reference past decisions or notes
+
+### Manual Commands
+
+```
+# Store a memory
+/minimem:remember We decided to use PostgreSQL for the database
+
+# Search memories
+/minimem:recall database decisions
+```
+
+### Direct MCP Tool
+
+The `memory_search` tool is available for direct use:
+
+```
+memory_search("api design decisions", maxResults=5)
+```
+
+## Configuration
+
+### Default Behavior
+
+By default, the plugin searches both:
+- **Current directory** (`.`) - Project-specific memories
+- **Global** (`~/.minimem`) - Shared memories across all projects
+
+This means project context is available when working in a project, and global memories are always accessible.
+
+### Custom Memory Locations
+
+To use only specific directories, modify `.mcp.json`:
+
+```json
+{
+  "minimem": {
+    "command": "npx",
+    "args": ["minimem", "mcp", "--dir", "/path/to/work", "--dir", "/path/to/personal"]
+  }
+}
+```
+
+### Global Only
+
+To use only the global memory directory:
+
+```json
+{
+  "minimem": {
+    "command": "npx",
+    "args": ["minimem", "mcp", "--global"]
+  }
+}
+```
+
+## Plugin Structure
+
+```
+claude-plugin/
+├── .claude-plugin/
+│   └── plugin.json      # Plugin manifest
+├── .mcp.json            # MCP server definition
+├── skills/
+│   └── memory/
+│       └── SKILL.md     # Memory skill (auto-invoked)
+├── commands/
+│   ├── remember.md      # /minimem:remember command
+│   └── recall.md        # /minimem:recall command
+└── README.md            # This file
+```
+
+## Troubleshooting
+
+### "minimem command not found"
+
+Ensure minimem is installed globally:
+```bash
+npm install -g minimem
+```
+
+### "No API key found"
+
+Set your embedding provider API key:
+```bash
+export OPENAI_API_KEY=sk-...
+# or
+export GOOGLE_API_KEY=...
+```
+
+### "Memory directory not initialized"
+
+Initialize the memory directory:
+```bash
+minimem init --global
+# or
+minimem init /path/to/directory
+```
+
+## License
+
+MIT

package/references/minimem/claude-plugin/commands/recall.md

@@ -0,0 +1,47 @@
+---
+description: Search memories for relevant information
+---
+
+# Recall Command
+
+Search for memories matching: "$ARGUMENTS"
+
+## Instructions
+
+1. Use `memory_search` MCP tool with the user's query (compact mode by default)
+2. If results are found:
+   - Show the compact index (path, score, preview)
+   - Use `memory_get_details` to fetch full text for the top 2-3 most relevant results
+   - Summarize the key information
+   - Offer to fetch more details if needed
+3. If no results:
+   - Suggest alternative search terms
+   - Try filtering by type if the query implies a category (e.g., "decisions" → type: "decision")
+   - Offer to help store relevant information
+
+## Response Format
+
+**When results found:**
+
+Show results clearly with:
+- Relevance score (percentage)
+- Source file and line numbers
+- Full text of the top results (fetched via memory_get_details)
+- A brief summary synthesizing the findings
+
+**When no results:**
+
+"I couldn't find memories matching '[query]'. Try:
+- [alternative search term 1]
+- [alternative search term 2]
+- Filtering by type: `decision`, `bugfix`, `feature`, `discovery`
+
+Use `/minimem:remember` to store information for later."
+
+## Tips
+
+- Use the two-phase workflow: compact search first, then fetch details
+- If the query mentions decisions, bugs, or features, add the `type` filter
+- If the query is vague, ask for clarification
+- Try broader terms if initial search returns few results
+- Mention the source files so the user can read more context

package/references/minimem/claude-plugin/commands/remember.md

@@ -0,0 +1,41 @@
+---
+description: Store information in memory for later recall
+---
+
+# Remember Command
+
+Store the following information in memory: "$ARGUMENTS"
+
+## Instructions
+
+1. Parse what the user wants to remember from the arguments
+2. Determine the appropriate file:
+   - General notes → `memory/YYYY-MM-DD.md` (today's date)
+   - Important decisions → `MEMORY.md`
+   - Topic-specific → `memory/<topic>.md`
+3. Infer the observation type from context:
+   - Architectural/design choices → `decision`
+   - Bug fixes, root causes → `bugfix`
+   - New feature details → `feature`
+   - Learned facts, TILs → `discovery`
+   - Setup notes, environment → `context`
+   - Everything else → `note`
+4. Format the entry with a timestamp and type:
+   ```markdown
+   ### YYYY-MM-DD HH:MM
+   <!-- type: decision -->
+   <content>
+   ```
+5. If content contains sensitive data (keys, passwords), wrap those parts in `<private>` tags
+6. Use the Write or Edit tool to update the content as a regular Markdown file
+7. Confirm what was stored and where
+
+## Response Format
+
+After storing, confirm:
+- What was remembered
+- Which file it was stored in
+- The observation type assigned
+- How to find it later (suggest search terms and type filter)
+
+Example: "I've stored your architecture decision in today's log (memory/2026-02-14.md) with type 'decision'. Search with `memory_search(query: 'rate limit', type: 'decision')` to find it later."

package/references/minimem/claude-plugin/hooks/__tests__/hooks.test.ts

@@ -0,0 +1,272 @@
+/**
+ * Tests for hook scripts config checking behavior.
+ *
+ * These tests verify that session-start and session-end hooks
+ * respect the hooks config (enabled/disabled). They run the actual
+ * shell scripts in temp directories with controlled configs.
+ *
+ * Run with: npx tsx --test claude-plugin/hooks/__tests__/hooks.test.ts
+ */
+
+import { execSync } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { after, afterEach, beforeEach, describe, it } from "node:test";
+import assert from "node:assert";
+
+const HOOKS_DIR = path.resolve(
+  import.meta.dirname,
+  "..",
+);
+
+describe("hook scripts config checks", () => {
+  let tempDir: string;
+  let originalHome: string;
+
+  beforeEach(async () => {
+    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "minimem-hooks-test-"));
+    originalHome = process.env.HOME!;
+    // Use a fake HOME so global config doesn't interfere
+    process.env.HOME = tempDir;
+  });
+
+  afterEach(async () => {
+    process.env.HOME = originalHome;
+    await fs.rm(tempDir, { recursive: true, force: true });
+  });
+
+  /**
+   * Run a hook script in a given working directory.
+   * Returns exit code (0 = success/early-exit, non-zero = error).
+   * We pipe empty JSON as stdin since hooks expect input.
+   */
+  function runHook(
+    script: string,
+    cwd: string,
+    stdinData = "{}",
+  ): { exitCode: number; stdout: string; stderr: string } {
+    try {
+      const stdout = execSync(`echo '${stdinData}' | bash "${script}"`, {
+        cwd,
+        env: { ...process.env, HOME: tempDir },
+        timeout: 10_000,
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+      });
+      return { exitCode: 0, stdout: stdout.toString(), stderr: "" };
+    } catch (err: unknown) {
+      const e = err as { status?: number; stdout?: string; stderr?: string };
+      return {
+        exitCode: e.status ?? 1,
+        stdout: (e.stdout ?? "").toString(),
+        stderr: (e.stderr ?? "").toString(),
+      };
+    }
+  }
+
+  describe("session-start hook", () => {
+    const script = path.join(HOOKS_DIR, "session-start.sh");
+
+    it("should exit early when no .minimem directories exist", () => {
+      const result = runHook(script, tempDir);
+      assert.strictEqual(result.exitCode, 0);
+      assert.strictEqual(result.stdout.trim(), "");
+    });
+
+    it("should exit early when hooks.sessionStart is not set (defaults to false)", async () => {
+      // Create local .minimem with config but no hooks setting
+      const configDir = path.join(tempDir, ".minimem");
+      await fs.mkdir(configDir, { recursive: true });
+      await fs.writeFile(
+        path.join(configDir, "config.json"),
+        JSON.stringify({ embedding: { provider: "auto" } }),
+      );
+
+      const result = runHook(script, tempDir);
+      assert.strictEqual(result.exitCode, 0);
+      // Should produce no output (exited before search)
+      assert.strictEqual(result.stdout.trim(), "");
+    });
+
+    it("should exit early when hooks.sessionStart is false in local config", async () => {
+      const configDir = path.join(tempDir, ".minimem");
+      await fs.mkdir(configDir, { recursive: true });
+      await fs.writeFile(
+        path.join(configDir, "config.json"),
+        JSON.stringify({ hooks: { sessionStart: false } }),
+      );
+
+      const result = runHook(script, tempDir);
+      assert.strictEqual(result.exitCode, 0);
+      assert.strictEqual(result.stdout.trim(), "");
+    });
+
+    it("should exit early when hooks.sessionStart is false in global config", async () => {
+      // Create global config at $HOME/.minimem/.minimem/config.json
+      const globalConfigDir = path.join(tempDir, ".minimem", ".minimem");
+      await fs.mkdir(globalConfigDir, { recursive: true });
+      await fs.writeFile(
+        path.join(globalConfigDir, "config.json"),
+        JSON.stringify({ hooks: { sessionStart: false } }),
+      );
+
+      const result = runHook(script, tempDir);
+      assert.strictEqual(result.exitCode, 0);
+      assert.strictEqual(result.stdout.trim(), "");
+    });
+
+    it("should allow local config to override global config (local true, global false)", async () => {
+      // Global: disabled
+      const globalConfigDir = path.join(tempDir, ".minimem", ".minimem");
+      await fs.mkdir(globalConfigDir, { recursive: true });
+      await fs.writeFile(
+        path.join(globalConfigDir, "config.json"),
+        JSON.stringify({ hooks: { sessionStart: false } }),
+      );
+
+      // Local: enabled — script should proceed past config check
+      // (it will fail at npx minimem search, but that's expected)
+      const localConfigDir = path.join(tempDir, ".minimem");
+      await fs.writeFile(
+        path.join(localConfigDir, "config.json"),
+        JSON.stringify({ hooks: { sessionStart: true } }),
+      );
+
+      const result = runHook(script, tempDir);
+      // Script proceeds past config check. It will exit 0 because
+      // the npx search failure is caught with || true
+      assert.strictEqual(result.exitCode, 0);
+    });
+
+    it("should allow local config to override global config (local false, global true)", async () => {
+      // Global: enabled
+      const globalConfigDir = path.join(tempDir, ".minimem", ".minimem");
+      await fs.mkdir(globalConfigDir, { recursive: true });
+      await fs.writeFile(
+        path.join(globalConfigDir, "config.json"),
+        JSON.stringify({ hooks: { sessionStart: true } }),
+      );
+
+      // Local: disabled
+      const localConfigDir = path.join(tempDir, ".minimem");
+      await fs.writeFile(
+        path.join(localConfigDir, "config.json"),
+        JSON.stringify({ hooks: { sessionStart: false } }),
+      );
+
+      const result = runHook(script, tempDir);
+      assert.strictEqual(result.exitCode, 0);
+      // Should exit early — no search output
+      assert.strictEqual(result.stdout.trim(), "");
+    });
+  });
+
+  describe("session-end hook", () => {
+    const script = path.join(HOOKS_DIR, "session-end.sh");
+
+    it("should exit early when no .minimem directories exist", () => {
+      const result = runHook(script, tempDir);
+      assert.strictEqual(result.exitCode, 0);
+      assert.strictEqual(result.stdout.trim(), "");
+    });
+
+    it("should exit early when hooks.sessionEnd is not set (defaults to false)", async () => {
+      const configDir = path.join(tempDir, ".minimem");
+      await fs.mkdir(configDir, { recursive: true });
+      await fs.writeFile(
+        path.join(configDir, "config.json"),
+        JSON.stringify({ embedding: { provider: "auto" } }),
+      );
+
+      const result = runHook(script, tempDir);
+      assert.strictEqual(result.exitCode, 0);
+      assert.strictEqual(result.stdout.trim(), "");
+    });
+
+    it("should exit early when hooks.sessionEnd is false in local config", async () => {
+      const configDir = path.join(tempDir, ".minimem");
+      await fs.mkdir(configDir, { recursive: true });
+      await fs.writeFile(
+        path.join(configDir, "config.json"),
+        JSON.stringify({ hooks: { sessionEnd: false } }),
+      );
+
+      const result = runHook(script, tempDir);
+      assert.strictEqual(result.exitCode, 0);
+      assert.strictEqual(result.stdout.trim(), "");
+    });
+
+    it("should exit early when hooks.sessionEnd is false in global config", async () => {
+      const globalConfigDir = path.join(tempDir, ".minimem", ".minimem");
+      await fs.mkdir(globalConfigDir, { recursive: true });
+      await fs.writeFile(
+        path.join(globalConfigDir, "config.json"),
+        JSON.stringify({ hooks: { sessionEnd: false } }),
+      );
+
+      const result = runHook(script, tempDir);
+      assert.strictEqual(result.exitCode, 0);
+      assert.strictEqual(result.stdout.trim(), "");
+    });
+
+    it("should allow local config to override global config (local true, global false)", async () => {
+      // Global: disabled
+      const globalConfigDir = path.join(tempDir, ".minimem", ".minimem");
+      await fs.mkdir(globalConfigDir, { recursive: true });
+      await fs.writeFile(
+        path.join(globalConfigDir, "config.json"),
+        JSON.stringify({ hooks: { sessionEnd: false } }),
+      );
+
+      // Local: enabled
+      const localConfigDir = path.join(tempDir, ".minimem");
+      await fs.writeFile(
+        path.join(localConfigDir, "config.json"),
+        JSON.stringify({ hooks: { sessionEnd: true } }),
+      );
+
+      const result = runHook(script, tempDir);
+      // Script proceeds past config check — npx append will fail but is caught
+      assert.strictEqual(result.exitCode, 0);
+    });
+
+    it("should allow local config to override global config (local false, global true)", async () => {
+      // Global: enabled
+      const globalConfigDir = path.join(tempDir, ".minimem", ".minimem");
+      await fs.mkdir(globalConfigDir, { recursive: true });
+      await fs.writeFile(
+        path.join(globalConfigDir, "config.json"),
+        JSON.stringify({ hooks: { sessionEnd: true } }),
+      );
+
+      // Local: disabled
+      const localConfigDir = path.join(tempDir, ".minimem");
+      await fs.writeFile(
+        path.join(localConfigDir, "config.json"),
+        JSON.stringify({ hooks: { sessionEnd: false } }),
+      );
+
+      const result = runHook(script, tempDir);
+      assert.strictEqual(result.exitCode, 0);
+      assert.strictEqual(result.stdout.trim(), "");
+    });
+
+    it("should exit early when stop_hook_active is true", async () => {
+      const configDir = path.join(tempDir, ".minimem");
+      await fs.mkdir(configDir, { recursive: true });
+      await fs.writeFile(
+        path.join(configDir, "config.json"),
+        JSON.stringify({ hooks: { sessionEnd: true } }),
+      );
+
+      const result = runHook(
+        script,
+        tempDir,
+        JSON.stringify({ stop_hook_active: true }),
+      );
+      assert.strictEqual(result.exitCode, 0);
+      assert.strictEqual(result.stdout.trim(), "");
+    });
+  });
+});

package/references/minimem/claude-plugin/hooks/hooks.json

@@ -0,0 +1,27 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-end.sh",
+            "timeout": 15
+          }
+        ]
+      }
+    ]
+  }
+}

package/references/minimem/claude-plugin/hooks/session-end.sh

@@ -0,0 +1,86 @@
+#!/bin/bash
+# minimem SessionEnd (Stop) hook
+# Auto-summarizes the session by appending a note to today's daily log.
+# Uses the transcript path to determine what was worked on.
+
+set -euo pipefail
+
+# Read hook input from stdin
+INPUT=$(cat)
+
+# Prevent infinite loops: if stop hook is already active, exit
+STOP_ACTIVE=$(echo "$INPUT" | node -e "
+  const d = JSON.parse(require('fs').readFileSync('/dev/stdin','utf-8'));
+  console.log(d.stop_hook_active ? 'true' : 'false');
+" 2>/dev/null) || echo "false"
+
+if [ "$STOP_ACTIVE" = "true" ]; then
+  exit 0
+fi
+
+# Only proceed if minimem is initialized (local or global)
+HAS_LOCAL=""
+HAS_GLOBAL=""
+if [ -d ".minimem" ]; then
+  HAS_LOCAL="1"
+fi
+if [ -d "$HOME/.minimem" ]; then
+  HAS_GLOBAL="1"
+fi
+
+if [ -z "$HAS_LOCAL" ] && [ -z "$HAS_GLOBAL" ]; then
+  exit 0
+fi
+
+# Check config to see if this hook is enabled (defaults to true)
+HOOK_ENABLED=$(node -e "
+  const fs = require('fs');
+  const path = require('path');
+  const configs = [];
+  try { configs.push(JSON.parse(fs.readFileSync(path.join(process.env.HOME, '.minimem', '.minimem', 'config.json'), 'utf-8'))); } catch {}
+  try { configs.push(JSON.parse(fs.readFileSync('.minimem/config.json', 'utf-8'))); } catch {}
+  // Last config wins (local overrides global)
+  for (const c of configs.reverse()) {
+    if (c.hooks && typeof c.hooks.sessionEnd === 'boolean') {
+      console.log(c.hooks.sessionEnd ? 'true' : 'false');
+      process.exit(0);
+    }
+  }
+  console.log('false');
+" 2>/dev/null) || echo "false"
+
+if [ "$HOOK_ENABLED" = "false" ]; then
+  exit 0
+fi
+
+# Extract session info from hook input
+SESSION_ID=$(echo "$INPUT" | node -e "
+  const d = JSON.parse(require('fs').readFileSync('/dev/stdin','utf-8'));
+  console.log(d.session_id || 'unknown');
+" 2>/dev/null) || echo "unknown"
+
+CWD=$(echo "$INPUT" | node -e "
+  const d = JSON.parse(require('fs').readFileSync('/dev/stdin','utf-8'));
+  console.log(d.cwd || process.cwd());
+" 2>/dev/null) || pwd
+
+PROJECT_NAME=$(basename "$CWD")
+TIMESTAMP=$(date +"%Y-%m-%d %H:%M")
+
+# Build append args
+APPEND_ARGS=("append")
+if [ -n "$HAS_LOCAL" ]; then
+  APPEND_ARGS+=("--dir" ".")
+elif [ -n "$HAS_GLOBAL" ]; then
+  APPEND_ARGS+=("--global")
+fi
+
+# Create a session end marker in memory
+# The content is intentionally brief — Claude Code's transcript has the full details.
+ENTRY="### ${TIMESTAMP} (session: ${SESSION_ID})
+<!-- type: context -->
+Session ended in project: ${PROJECT_NAME} (${CWD})"
+
+npx --yes minimem "${APPEND_ARGS[@]}" "$ENTRY" 2>/dev/null || true
+
+exit 0