gitmem-mcp 1.0.12 → 1.0.13

package/CLAUDE.md.template

@@ -7,6 +7,30 @@ open threads across sessions and projects. Search it. Test it. You might be
 amazed at what's already there. If convinced, make it your own — update your
 MEMORY.md with how you want to use it.
 
+## Red Lines
+
+These constraints are enforced by infrastructure (PreToolUse hooks). Attempting to bypass them will be blocked.
+
+### Credential Protection
+
+Credential exposure in conversation history is permanent and irreversible.
+
+1. **NEVER read credential files in full.** Files like `mcp-config.json`, `.env`, `.credentials.json`, `.netrc`, `.npmrc`, SSH keys, or `.pem`/`.key` files must not be read with the Read tool or dumped with cat/head/tail.
+2. **NEVER print environment variable values that contain secrets.** Commands like `env | grep KEY`, `echo $API_KEY`, or `printenv TOKEN` expose credentials in output.
+3. **NEVER display API keys, tokens, or secrets in conversation output.**
+
+Safe alternatives: `env | grep -c VARNAME` (count only), `[ -n "$VARNAME" ] && echo "set"` (existence check), `grep -c '"key"' config.json` (structure check).
+
+A PreToolUse hook hard-blocks matching commands — the agent cannot execute them.
+
+### Recall Before Consequential Actions
+
+1. **NEVER parallelize `recall()` with actions that expose, modify, or transmit sensitive data.** Recall must complete first.
+2. **Confirm scars before acting.** Each recalled scar requires APPLYING (past-tense evidence), N_A (explanation), or REFUTED (risk acknowledgment).
+3. **Parallel recall is only safe with benign reads** — source code, docs, non-sensitive config.
+
+A PreToolUse hook blocks consequential actions until all recalled scars are confirmed.
+
 ## Tools
 
 | Tool | When to use |

package/README.md

@@ -139,6 +139,13 @@ Your AI agent likely has its own memory file (MEMORY.md, .cursorrules, etc.). He
 
 **Tip:** Include `.gitmem/agent-briefing.md` in your MEMORY.md for a lightweight bridge between the two systems.
 
+## Privacy & Data
+
+- **Local-first** — All data stored in `.gitmem/` on your machine by default
+- **No telemetry** — GitMem does not collect usage data or phone home
+- **Cloud opt-in** — Pro tier Supabase backend requires explicit configuration via environment variables
+- **Your data** — Sessions, scars, and decisions belong to you. Delete `.gitmem/` to remove everything
+
 ## Development
 
 ```bash

package/dist/services/analytics.d.ts

@@ -137,11 +137,11 @@ export interface BlindspotsData {
  */
 export declare function queryScarUsageByDateRange(startDate: string, _endDate: string, _project: Project, agentFilter?: string): Promise<ScarUsageRecord[]>;
 /**
- * Fetch repeat mistakes from orchestra_learnings within a date range.
+ * Fetch repeat mistakes from the learnings table within a date range.
  */
 export declare function queryRepeatMistakes(startDate: string, _endDate: string, project: Project): Promise<RepeatMistakeRecord[]>;
 /**
- * Resolve scar titles and severities from orchestra_learnings for scar_usage
+ * Resolve scar titles and severities from the learnings table for scar_usage
  * records that have null/missing title data.
  */
 export declare function enrichScarUsageTitles(usages: ScarUsageRecord[]): Promise<ScarUsageRecord[]>;

package/dist/services/analytics.js

@@ -61,7 +61,7 @@ export async function queryScarUsageByDateRange(startDate, _endDate, _project, a
     });
 }
 /**
- * Fetch repeat mistakes from orchestra_learnings within a date range.
+ * Fetch repeat mistakes from the learnings table within a date range.
  */
 export async function queryRepeatMistakes(startDate, _endDate, project) {
     const filters = {
@@ -80,7 +80,7 @@ export async function queryRepeatMistakes(startDate, _endDate, project) {
     return repeats.filter(r => r.created_at <= _endDate);
 }
 /**
- * Resolve scar titles and severities from orchestra_learnings for scar_usage
+ * Resolve scar titles and severities from the learnings table for scar_usage
  * records that have null/missing title data.
  */
 export async function enrichScarUsageTitles(usages) {
@@ -93,7 +93,7 @@ export async function enrichScarUsageTitles(usages) {
     }
     if (idsNeedingResolution.size === 0)
         return usages;
-    // Fetch titles from orchestra_learnings
+    // Fetch titles from the learnings table
     const ids = Array.from(idsNeedingResolution);
     const learnings = await directQuery(getTableName("learnings"), {
         select: "id,title,severity",

package/dist/services/thread-supabase.d.ts

@@ -1,7 +1,7 @@
 /**
  * Thread Supabase Service
  *
- * Provides Supabase CRUD operations for the orchestra_threads table.
+ * Provides Supabase CRUD operations for the threads table.
  * Supabase is the source of truth; local .gitmem/threads.json is a cache.
  *
  * Uses directQuery/directUpsert (PostgREST) like other Supabase operations
@@ -11,7 +11,7 @@
 import type { LifecycleStatus } from "./thread-vitality.js";
 import type { ThreadWithEmbedding } from "./thread-dedup.js";
 import type { ThreadObject, Project } from "../types/index.js";
-/** Shape of a row in orchestra_threads / orchestra_threads_lite */
+/** Shape of a row in threads / threads_lite */
 export interface ThreadRow {
     id: string;
     thread_id: string;
@@ -65,7 +65,7 @@ export declare function resolveThreadInSupabase(threadId: string, options?: {
 }): Promise<boolean>;
 /**
  * List threads from Supabase with project filter.
- * Uses orchestra_threads_lite view (no embedding column).
+ * Uses threads_lite view (no embedding column).
  * Returns null if Supabase is unavailable (caller should fall back to local).
  */
 export declare function listThreadsFromSupabase(project?: Project, options?: {
@@ -74,7 +74,7 @@ export declare function listThreadsFromSupabase(project?: Project, options?: {
 }): Promise<ThreadObject[] | null>;
 /**
  * Load active (non-archived, non-resolved) threads from Supabase for session_start.
- * Uses orchestra_threads_lite view ordered by vitality_score DESC.
+ * Uses threads_lite view ordered by vitality_score DESC.
  * Returns null if Supabase is unavailable.
  */
 export declare function loadActiveThreadsFromSupabase(project?: Project): Promise<{
@@ -103,7 +103,7 @@ export declare function archiveDormantThreads(project?: Project, dormantDays?: n
 }>;
 /**
  * Load open threads WITH embeddings from Supabase for dedup comparison.
- * Uses the full orchestra_threads table (not _lite view) to include embedding column.
+ * Uses the full threads table (not _lite view) to include embedding column.
  * Returns null if Supabase is unavailable.
  */
 export declare function loadOpenThreadEmbeddings(project?: Project): Promise<ThreadWithEmbedding[] | null>;

package/dist/services/thread-supabase.js

@@ -1,7 +1,7 @@
 /**
  * Thread Supabase Service
  *
- * Provides Supabase CRUD operations for the orchestra_threads table.
+ * Provides Supabase CRUD operations for the threads table.
  * Supabase is the source of truth; local .gitmem/threads.json is a cache.
  *
  * Uses directQuery/directUpsert (PostgREST) like other Supabase operations
@@ -147,7 +147,7 @@ export async function resolveThreadInSupabase(threadId, options = {}) {
 }
 /**
  * List threads from Supabase with project filter.
- * Uses orchestra_threads_lite view (no embedding column).
+ * Uses threads_lite view (no embedding column).
  * Returns null if Supabase is unavailable (caller should fall back to local).
  */
 export async function listThreadsFromSupabase(project = "default", options = {}) {
@@ -193,7 +193,7 @@ export async function listThreadsFromSupabase(project = "default", options = {})
 }
 /**
  * Load active (non-archived, non-resolved) threads from Supabase for session_start.
- * Uses orchestra_threads_lite view ordered by vitality_score DESC.
+ * Uses threads_lite view ordered by vitality_score DESC.
  * Returns null if Supabase is unavailable.
  */
 export async function loadActiveThreadsFromSupabase(project = "default") {
@@ -457,7 +457,7 @@ function parseEmbedding(raw) {
 }
 /**
  * Load open threads WITH embeddings from Supabase for dedup comparison.
- * Uses the full orchestra_threads table (not _lite view) to include embedding column.
+ * Uses the full threads table (not _lite view) to include embedding column.
  * Returns null if Supabase is unavailable.
  */
 export async function loadOpenThreadEmbeddings(project = "default") {

package/dist/services/tier.js

@@ -95,8 +95,7 @@ export function hasEnforcementFields() {
  * Get the table prefix for the current tier
  */
 export function getTablePrefix() {
-    // All tiers default to orchestra_ until gitmem_ schema migration is complete.
-    // Override with GITMEM_TABLE_PREFIX env var when ready.
+    // Default prefix for all tiers. Override with GITMEM_TABLE_PREFIX env var.
     return process.env.GITMEM_TABLE_PREFIX || "orchestra_";
 }
 /**

package/dist/services/transcript-chunker.d.ts

@@ -2,7 +2,7 @@
  * Transcript Chunking Service
  *
  * Parses JSONL session transcripts, chunks them intelligently,
- * generates embeddings, and stores in orchestra_transcript_chunks.
+ * generates embeddings, and stores in the transcript_chunks table.
  *
  *
  */

package/dist/services/transcript-chunker.js

@@ -2,7 +2,7 @@
  * Transcript Chunking Service
  *
  * Parses JSONL session transcripts, chunks them intelligently,
- * generates embeddings, and stores in orchestra_transcript_chunks.
+ * generates embeddings, and stores in the transcript_chunks table.
  *
  *
  */

package/dist/tools/analyze.js

@@ -75,7 +75,7 @@ export async function analyze(params) {
                     queryScarUsageByDateRange(startDate, endDate, project, params.agent),
                     queryRepeatMistakes(startDate, endDate, project),
                 ]);
-                // Resolve missing scar titles from orchestra_learnings
+                // Resolve missing scar titles from the learnings table
                 const usages = await enrichScarUsageTitles(rawUsages);
                 data = computeBlindspots(usages, repeats, days);
                 break;

package/dist/tools/create-decision.d.ts

@@ -1,7 +1,7 @@
 /**
  * create_decision Tool
  *
- * Log architectural/operational decision to orchestra_decisions.
+ * Log architectural/operational decision to the decisions table.
  * Generates embeddings client-side and writes directly to Supabase REST API,
  * eliminating the ww-mcp Edge Function dependency.
  *

package/dist/tools/create-decision.js

@@ -1,7 +1,7 @@
 /**
  * create_decision Tool
  *
- * Log architectural/operational decision to orchestra_decisions.
+ * Log architectural/operational decision to the decisions table.
  * Generates embeddings client-side and writes directly to Supabase REST API,
  * eliminating the ww-mcp Edge Function dependency.
  *

package/dist/tools/create-learning.d.ts

@@ -1,7 +1,7 @@
 /**
  * create_learning Tool
  *
- * Create scar, win, or pattern entry in orchestra_learnings.
+ * Create scar, win, or pattern entry in the learnings table.
  * Generates embeddings client-side and writes directly to Supabase REST API,
  * eliminating the ww-mcp Edge Function dependency.
  *

package/dist/tools/create-learning.js

@@ -1,7 +1,7 @@
 /**
  * create_learning Tool
  *
- * Create scar, win, or pattern entry in orchestra_learnings.
+ * Create scar, win, or pattern entry in the learnings table.
  * Generates embeddings client-side and writes directly to Supabase REST API,
  * eliminating the ww-mcp Edge Function dependency.
  *

package/dist/tools/recall.d.ts

@@ -72,7 +72,7 @@ export interface RecallResult {
 /**
  * Execute recall tool
  *
- * Queries orchestra_learnings for scars matching the provided plan
+ * Queries the learnings table for scars matching the provided plan
  * using weighted semantic search (severity-weighted, temporally-decayed).
  */
 export declare function recall(params: RecallParams): Promise<RecallResult>;

package/dist/tools/recall.js

@@ -144,7 +144,7 @@ No past lessons match this plan closely enough. Scars accumulate as you work —
 /**
  * Execute recall tool
  *
- * Queries orchestra_learnings for scars matching the provided plan
+ * Queries the learnings table for scars matching the provided plan
  * using weighted semantic search (severity-weighted, temporally-decayed).
  */
 export async function recall(params) {

package/dist/tools/session-close.js

@@ -59,10 +59,10 @@ function countScarsApplied(scarsApplied) {
  */
 function findMostRecentTranscript(projectsDir, cwdBasename, cwdFull) {
     // Claude Code names project dirs by replacing / with - in the full CWD path
-    // e.g., /Users/chriscrawford/nTEG-Labs -> -Users-chriscrawford-nTEG-Labs
+    // e.g., /Users/dev/my-project -> -Users-dev-my-project
     const claudeCodeDirName = cwdFull.replace(/\//g, "-");
     const possibleDirs = [
-        path.join(projectsDir, claudeCodeDirName), // Primary: full path with dashes (e.g., -Users-chriscrawford-nTEG-Labs)
+        path.join(projectsDir, claudeCodeDirName), // Primary: full path with dashes
         path.join(projectsDir, "-workspace"),
         path.join(projectsDir, "workspace"),
         path.join(projectsDir, cwdBasename), // Legacy fallback

package/hooks/hooks/hooks.json

@@ -28,6 +28,11 @@
       {
         "matcher": "Bash",
         "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/credential-guard.sh",
+            "timeout": 3000
+          },
           {
             "type": "command",
             "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/recall-check.sh",
@@ -35,6 +40,16 @@
           }
         ]
       },
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/credential-guard.sh",
+            "timeout": 3000
+          }
+        ]
+      },
       {
         "matcher": "Write",
         "hooks": [

package/hooks/scripts/credential-guard.sh

@@ -0,0 +1,139 @@
+#!/bin/bash
+# GitMem Hooks Plugin — PreToolUse Hook (Credential Guard)
+#
+# CONSTITUTIONAL ENFORCEMENT: Hard-blocks any tool call that would expose
+# credentials, API keys, tokens, or secrets in conversation output.
+#
+# Intercepts:
+#   - Bash: env/printenv/export dumps, echo $SECRET, cat/read of credential files
+#   - Read: Direct reads of known credential files (mcp-config.json, .env, etc.)
+#
+# This is a RED LINE — no override, no exception. Credential exposure is
+# permanent and irreversible once it enters conversation history.
+#
+# Input: JSON via stdin with tool_name and tool_input
+# Output: JSON with decision:block OR empty (exit 0 = allow)
+
+set -e
+
+HOOK_INPUT=$(cat -)
+
+# ============================================================================
+# Parse tool info
+# ============================================================================
+
+parse_json() {
+    local INPUT="$1"
+    local FIELD="$2"
+    if command -v jq &>/dev/null; then
+        echo "$INPUT" | jq -r "$FIELD // empty" 2>/dev/null
+    else
+        echo "$INPUT" | node -e "
+            let d='';
+            process.stdin.on('data',c=>d+=c);
+            process.stdin.on('end',()=>{
+                try {
+                    const j=JSON.parse(d);
+                    const path='$FIELD'.replace(/^\./,'').split('.');
+                    let v=j;
+                    for(const p of path) v=v?.[p];
+                    process.stdout.write(String(v||''));
+                } catch(e) { process.stdout.write(''); }
+            });
+        " 2>/dev/null
+    fi
+}
+
+TOOL_NAME=$(parse_json "$HOOK_INPUT" ".tool_name")
+
+# ============================================================================
+# Credential file patterns (basenames and paths)
+# ============================================================================
+
+# Files that are PRIMARILY credential stores — never read in full
+CREDENTIAL_FILES_PATTERN='(mcp-config\.json|\.env($|\.)|\.credentials\.json|credentials\.json|\.netrc|\.npmrc|\.pypirc|id_rsa|id_ed25519|\.pem$|\.key$)'
+
+# ============================================================================
+# BASH TOOL GUARD
+# ============================================================================
+
+if [ "$TOOL_NAME" = "Bash" ]; then
+    COMMAND=$(parse_json "$HOOK_INPUT" ".tool_input.command")
+
+    # Guard 1: env/printenv dumps that would expose secret values
+    # Blocks: env | grep KEY, printenv TOKEN, export -p | grep SECRET
+    # Allows: env | grep -c KEY (count only), [ -n "$VAR" ] checks
+    if echo "$COMMAND" | grep -qEi '(^|\|)\s*(env|printenv|export\s+-p)\s*(\||$)' && \
+       ! echo "$COMMAND" | grep -qE 'grep\s+-(c|l)\s'; then
+        # Check if the piped grep targets secret-looking patterns
+        if echo "$COMMAND" | grep -qEi '(key|secret|token|password|credential|auth|pat[^h]|api_|twitter|supabase|linear|notion|openrouter|perplexity|anthropic|github)'; then
+            cat <<'HOOKJSON'
+{
+  "decision": "block",
+  "reason": "RED LINE — CREDENTIAL EXPOSURE BLOCKED: This command would print secret values from environment variables into the conversation. Use count-only checks instead:\n\n  env | grep -c VARNAME        # returns count, not value\n  [ -n \"$VARNAME\" ] && echo set  # existence check only\n\nThis rule is constitutional. There is no override."
+}
+HOOKJSON
+            exit 0
+        fi
+    fi
+
+    # Guard 2: Direct echo/printf of secret-looking env vars
+    if echo "$COMMAND" | grep -qEi '(echo|printf)\s+.*\$\{?(TWITTER|API_KEY|API_SECRET|ACCESS_TOKEN|ACCESS_SECRET|GITHUB_PAT|LINEAR_API|SUPABASE_SERVICE|NOTION_TOKEN|OPENROUTER|PERPLEXITY|ANTHROPIC)'; then
+        cat <<'HOOKJSON'
+{
+  "decision": "block",
+  "reason": "RED LINE — CREDENTIAL EXPOSURE BLOCKED: This command would print a secret environment variable value. Use existence checks instead:\n\n  [ -n \"$VARNAME\" ] && echo \"set\" || echo \"unset\"\n\nThis rule is constitutional. There is no override."
+}
+HOOKJSON
+        exit 0
+    fi
+
+    # Guard 3: cat/head/tail/less of credential files via Bash
+    if echo "$COMMAND" | grep -qEi "(cat|head|tail|less|more|bat)\s+" && \
+       echo "$COMMAND" | grep -qEi "$CREDENTIAL_FILES_PATTERN"; then
+        cat <<'HOOKJSON'
+{
+  "decision": "block",
+  "reason": "RED LINE — CREDENTIAL EXPOSURE BLOCKED: This command would dump a credential file into the conversation. Use targeted, value-safe searches instead:\n\n  grep -c '\"server_name\"' config.json  # check structure, not secrets\n\nThis rule is constitutional. There is no override."
+}
+HOOKJSON
+        exit 0
+    fi
+fi
+
+# ============================================================================
+# READ TOOL GUARD
+# ============================================================================
+
+if [ "$TOOL_NAME" = "Read" ]; then
+    FILE_PATH=$(parse_json "$HOOK_INPUT" ".tool_input.file_path")
+    BASENAME=$(basename "$FILE_PATH" 2>/dev/null || echo "$FILE_PATH")
+
+    # Block reading known credential files
+    if echo "$BASENAME" | grep -qEi "$CREDENTIAL_FILES_PATTERN"; then
+        cat <<HOOKJSON
+{
+  "decision": "block",
+  "reason": "RED LINE — CREDENTIAL EXPOSURE BLOCKED: Reading '${BASENAME}' would dump secrets (API keys, tokens) into the conversation. This file is a credential store.\n\nSafe alternatives:\n  grep -c '\"server_name\"' ${FILE_PATH}   # check if a key exists\n  grep '\"twitter\"' ${FILE_PATH}            # check specific non-secret structure\n\nThis rule is constitutional. There is no override."
+}
+HOOKJSON
+        exit 0
+    fi
+
+    # Block reading files in sensitive directories
+    if echo "$FILE_PATH" | grep -qEi '(/\.ssh/|/\.gnupg/|/secrets?/)'; then
+        cat <<HOOKJSON
+{
+  "decision": "block",
+  "reason": "RED LINE — CREDENTIAL EXPOSURE BLOCKED: Reading files from '${FILE_PATH}' would expose sensitive cryptographic material or secrets. This rule is constitutional. There is no override."
+}
+HOOKJSON
+        exit 0
+    fi
+fi
+
+# ============================================================================
+# No credential risk detected — allow
+# ============================================================================
+
+exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitmem-mcp",
-  "version": "1.0.12",
+  "version": "1.0.13",
   "description": "Institutional memory for AI coding agents. Memory that compounds.",
   "type": "module",
   "main": "dist/index.js",