Skip to content

pro-setup-guide.md

Latest commit

 

History

History
252 lines (180 loc) · 10.4 KB

pro-setup-guide.md

File metadata and controls

252 lines (180 loc) · 10.4 KB

GitMem Pro Setup Guide

Prerequisites

  • A Supabase project (free tier works)
  • An OpenRouter account (for embeddings/semantic search)
  • A GitMem Pro license key (gitmem_pro_...)
  • Supabase CLI installed (npm install -g supabase)

Setup

1. Set environment variables

Set these in your shell profile (.bashrc, .zshrc) or .env file:

export SUPABASE_URL="https://yourproject.supabase.co"
export SUPABASE_SERVICE_ROLE_KEY="eyJ..."
export OPENROUTER_API_KEY="sk-or-v1-..."
export DATABASE_URL="postgresql://postgres.yourref:yourpassword@aws-0-region.pooler.supabase.com:5432/postgres"

Where to find these:

  • SUPABASE_URL: Supabase Dashboard → Settings → API → Project URL
  • SUPABASE_SERVICE_ROLE_KEY: Supabase Dashboard → Settings → API → service_role key (under "Project API keys")
  • OPENROUTER_API_KEY: openrouter.ai/keys → Create Key
  • DATABASE_URL: Supabase Dashboard → Connect → Connection string (Session pooler or Direct)

2. (Optional) Point at an existing schema with a custom table prefix

By default GitMem uses tables prefixed with gitmem_ (gitmem_learnings, gitmem_decisions, …). If you are pointing GitMem at a Supabase project whose tables use a different prefix — for example an existing orchestra_ schema you are not migrating yet — set:

export GITMEM_TABLE_PREFIX="orchestra_"

Important:

  • Env-only. The prefix is resolved at runtime by getTableName() (src/services/tier.ts). It is not read from .gitmem/config.json and cannot be set by activate. It must be present in every client's environment — your shell profile for the CLI and the env block of the MCP server entry in claude_desktop_config.json for the desktop app.
  • You own the tables. activate's auto-schema always creates gitmem_* tables; with a custom prefix it will not create your prefixed tables, so they must already exist on the target project.
  • Mismatch symptom. create_learning / create_decision fail with PostgREST PGRST205 ("table not in schema cache"), while threads appear to work — thread writes silently fall back to the local .gitmem cache, and gitmem-cache-health reads Supabase regardless of storage tier, so both can look healthy while writes go nowhere. See the write-path health check.

3. Activate

npx gitmem-mcp activate <your-license-key>

This does everything:

  • Validates your license key
  • Connects to your Supabase project
  • Creates all required tables, views, indexes, and RPC functions automatically
  • Saves credentials to .gitmem/config.json

You should see:

✓ Key validated (pro tier)
  ✓ Connected to Supabase
  ✓ Schema applied automatically
  ✓ OpenRouter configured (from env)

Pro tier activated! Restart your editor to apply.

4. Restart your editor

Restart Claude Code or Cursor so the MCP server picks up the pro configuration.

Credential options

You don't have to paste secrets into a terminal. The activate command resolves credentials in this order:

  1. Environment variables — set SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, OPENROUTER_API_KEY before running activate
  2. Config file — edit .gitmem/config.json directly with supabase_url, supabase_key, openrouter_key fields
  3. Interactive prompt — if running in a terminal, activate will prompt for any missing values

What gets created

The activate command creates these in your Supabase project (table and view names are prefixed by GITMEM_TABLE_PREFIX, default gitmem_):

Tables Purpose
gitmem_learnings Scars, wins, patterns with embeddings
gitmem_sessions Session history and reflections
gitmem_decisions Decision log with rationale
gitmem_scar_usage Tracks when scars are surfaced and applied
gitmem_threads Cross-session work items
gitmem_query_metrics Performance tracking
knowledge_triples Knowledge graph relationships
scar_enforcement_variants A/B testing for scar delivery
Views Purpose
gitmem_learnings_lite Learnings without embedding column (fast reads)
gitmem_sessions_lite Sessions without embedding column
gitmem_decisions_lite Decisions without embedding column
gitmem_threads_lite Threads without embedding column
RPC Functions Purpose
gitmem_semantic_search Vector similarity search across learnings
gitmem_scar_search Weighted search with temporal + behavioral decay
refresh_scar_behavioral_scores Updates decay weights from usage patterns

All tables have Row Level Security enabled with service role access only.

Pro tools

All tools work in both free and pro tiers. In free tier, data is stored locally in .gitmem/. In pro tier, data persists to Supabase with semantic vector search via embeddings.

Session lifecycle

Tool What it does
session_start Loads last session context, open threads, recent decisions
session_refresh Re-surface institutional context mid-session (after compaction)
session_close Persists session reflection, learnings, and compliance

Memory creation

Tool What it does
create_learning Store a scar, win, or pattern (with embedding in pro)
create_decision Log a decision with rationale and alternatives
record_scar_usage Track when a scar was surfaced and how it was applied

Retrieval

Tool What it does
recall Semantic search for relevant scars before taking action
confirm_scars Acknowledge recalled scars as APPLYING, N_A, or REFUTED
reflect_scars End-of-session scar reflection (how each was handled)
search Search institutional memory by keyword or semantics
log Browse recent learnings chronologically

Threads

Tool What it does
create_thread Track unresolved work across sessions
list_threads View open threads
resolve_thread Mark a thread as resolved
promote_suggestion Promote a suggested thread to an open thread
dismiss_suggestion Dismiss a suggested thread
cleanup_threads Triage threads by lifecycle health (active/cooling/dormant)

Multi-agent coordination

Tool What it does
prepare_context Generate compact memory payload for sub-agent injection
absorb_observations Capture and persist findings from sub-agents

Knowledge graph

Tool What it does
graph_traverse Traverse knowledge graph connections (connected_to, produced_by, provenance, stats)
archive_learning Archive a scar/win/pattern (excluded from recall, preserved for audit)

Analytics and diagnostics

Tool What it does
analyze Session analytics and insights (summary, reflections, blindspots)
health Show write health for the current session
contribute_feedback Submit feedback about gitmem

Document indexing

Tool What it does
index_docs Index a directory of markdown files for semantic search
search_docs Search indexed documentation

Transcripts (pro only)

Tool What it does
save_transcript Save a session transcript
get_transcript Retrieve a saved transcript
search_transcripts Search across saved transcripts

Cache management

Tool What it does
gitmem-cache-status Show local search cache status
gitmem-cache-health Compare local cache against remote Supabase
gitmem-cache-flush Force reload cache from Supabase

Most tools also have short aliases (gm-scar, gm-search, gm-threads, etc.) for faster invocation.

Deactivation

npx gitmem-mcp deactivate

This removes the device from the license server (freeing a device slot), clears credentials from config, and deletes the license cache. Your Supabase data is preserved — you can re-activate on the same or different device.

Troubleshooting

Schema not applied automatically

Auto-schema uses either DATABASE_URL (direct Postgres connection) or SUPABASE_ACCESS_TOKEN (Management API). If neither is available, apply manually:

# Option 1: Set DATABASE_URL and re-run
export DATABASE_URL="postgresql://postgres.ref:password@pooler.supabase.com:5432/postgres"
npx gitmem-mcp activate

# Option 2: Set SUPABASE_ACCESS_TOKEN and re-run
npx supabase login
npx gitmem-mcp activate

# Option 3: Apply manually
npx gitmem-mcp setup | pbcopy    # macOS — copies SQL to clipboard
npx gitmem-mcp setup             # prints SQL
# Then paste into Supabase Dashboard → SQL Editor → Run

Writes succeed but nothing appears in Supabase

create_learning / create_decision return a UUID but the row never shows up in your *_learnings table, and there is no PGRST205 error. This means GitMem fell back to free tier and wrote to a local .gitmem/ file instead of Supabase. With SUPABASE_URL set, the only path to free tier is an invalid or missing license, so check:

  • GITMEM_API_KEY is a real gitmem_pro_... key (not a placeholder), present in the same environment as the MCP server (e.g. the env block in claude_desktop_config.json, not just your shell).
  • The license validated — the startup log shows Tier: pro, not Tier: free / Tier updated: free.
  • The device limit (3) is not exhausted — see below.

Reads can be misleading here: gitmem-cache-health and recall may still reach Supabase while the write path is local. Confirm pro end-to-end by creating a learning and verifying the row exists in <prefix>learnings with a non-null embedding.

Device limit reached

Each license allows 3 concurrent devices. Deactivate unused devices:

npx gitmem-mcp deactivate   # on the device you want to free

Connection test fails

Verify your SUPABASE_URL ends with .supabase.co and your service role key is the full JWT (starts with eyJ).

Recall returns no results

Recall uses semantic search via embeddings. Make sure:

  • OPENROUTER_API_KEY is set (or OPENAI_API_KEY)
  • You've created at least one learning with create_learning
  • The learning has a description long enough to generate a meaningful embedding