Skip to content

Commit 745a0f5

Browse files
Claudeclaude
authored and
CLC
committed
docs: add Pro setup guide and update README
- New docs/pro-setup-guide.md with full user journey: prerequisites, setup steps, credential options, schema details, tool reference, deactivation, and troubleshooting - README updated: Pro tier section now reflects availability with quick start snippet and link to guide - CLI commands table updated with activate, deactivate, and setup Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent a92debf commit 745a0f5

2 files changed

Lines changed: 183 additions & 4 deletions

File tree

‎README.md‎

Lines changed: 21 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -124,23 +124,40 @@ Add this to your MCP client's config file:
124124
| `npx gitmem-mcp init --client <name>` | Setup for specific client (`claude`, `cursor`, `vscode`, `windsurf`, `generic`) |
125125
| `npx gitmem-mcp init --yes` | Non-interactive setup |
126126
| `npx gitmem-mcp init --dry-run` | Preview changes |
127+
| `npx gitmem-mcp activate <key>` | Activate Pro tier (auto-applies schema) |
128+
| `npx gitmem-mcp deactivate` | Remove Pro credentials, free device slot |
129+
| `npx gitmem-mcp setup` | Output schema SQL (for manual Supabase setup) |
127130
| `npx gitmem-mcp uninstall` | Clean removal (preserves `.gitmem/` data) |
128131
| `npx gitmem-mcp uninstall --all` | Full removal including data |
129132
| `npx gitmem-mcp check` | Diagnostic health check |
130133

131-
## Pro Tier — Coming Soon
134+
## Pro Tier
135+
136+
Self-hosted on your own Supabase. You bring the infrastructure, gitmem sets it up.
132137

133138
| What you get | Why your agent cares |
134139
|-------------|---------------------|
135140
| **Semantic search** | Recall returns the *right* scars, not keyword noise |
136141
| **Session analytics** | Spot patterns in what keeps going wrong |
137142
| **Sub-agent briefing** | Hand institutional context to sub-agents automatically |
138143
| **Cloud persistence** | Memory survives machine changes, shareable across team |
139-
| **A/B testing analytics** | Measure which scar phrasings actually change agent behavior (free tier includes `GITMEM_NUDGE_VARIANT` for manual testing) |
144+
| **A/B testing analytics** | Measure which scar phrasings actually change agent behavior |
140145

141-
The free tier gives you everything for solo projects. Pro makes recall smarter and memory portable.
146+
### Quick start
147+
148+
```bash
149+
npx supabase login # one time
150+
export SUPABASE_URL="https://yourproject.supabase.co"
151+
export SUPABASE_SERVICE_ROLE_KEY="eyJ..."
152+
export OPENROUTER_API_KEY="sk-or-v1-..."
153+
npx gitmem-mcp activate <your-license-key>
154+
```
155+
156+
The activate command creates all tables, views, RPC functions, and indexes automatically. No manual SQL needed.
142157

143-
[Join the mailing list](https://gitmem.ai) to get notified.
158+
See **[docs/pro-setup-guide.md](docs/pro-setup-guide.md)** for the full guide.
159+
160+
The free tier gives you everything for solo projects. Pro makes recall smarter and memory portable.
144161

145162
## GitMem + MEMORY.md
146163

‎docs/pro-setup-guide.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
# GitMem Pro Setup Guide
2+
3+
## Prerequisites
4+
5+
- A [Supabase](https://supabase.com) project (free tier works)
6+
- An [OpenRouter](https://openrouter.ai) account (for embeddings/semantic search)
7+
- A GitMem Pro license key (`gitmem_pro_...`)
8+
- Supabase CLI installed (`npm install -g supabase`)
9+
10+
## Setup
11+
12+
### 1. Log in to Supabase CLI
13+
14+
```bash
15+
npx supabase login
16+
```
17+
18+
This stores an access token locally that gitmem uses to set up your database schema automatically.
19+
20+
### 2. Set environment variables
21+
22+
Set these in your shell profile (`.bashrc`, `.zshrc`) or `.env` file:
23+
24+
```bash
25+
export SUPABASE_URL="https://yourproject.supabase.co"
26+
export SUPABASE_SERVICE_ROLE_KEY="eyJ..."
27+
export OPENROUTER_API_KEY="sk-or-v1-..."
28+
```
29+
30+
**Where to find these:**
31+
- **SUPABASE_URL**: Supabase Dashboard → Settings → API → Project URL
32+
- **SUPABASE_SERVICE_ROLE_KEY**: Supabase Dashboard → Settings → API → `service_role` key (under "Project API keys")
33+
- **OPENROUTER_API_KEY**: [openrouter.ai/keys](https://openrouter.ai/keys) → Create Key
34+
35+
### 3. Activate
36+
37+
```bash
38+
npx gitmem-mcp activate <your-license-key>
39+
```
40+
41+
This does everything:
42+
- Validates your license key
43+
- Connects to your Supabase project
44+
- Creates all required tables, views, indexes, and RPC functions automatically
45+
- Saves credentials to `.gitmem/config.json`
46+
47+
You should see:
48+
49+
```
50+
✓ Key validated (pro tier)
51+
✓ Connected to Supabase
52+
✓ Schema applied automatically
53+
✓ OpenRouter configured (from env)
54+
55+
Pro tier activated! Restart your editor to apply.
56+
```
57+
58+
### 4. Restart your editor
59+
60+
Restart Claude Code or Cursor so the MCP server picks up the pro configuration.
61+
62+
## Credential options
63+
64+
You don't have to paste secrets into a terminal. The activate command resolves credentials in this order:
65+
66+
1. **Environment variables** — set `SUPABASE_URL`, `SUPABASE_SERVICE_ROLE_KEY`, `OPENROUTER_API_KEY` before running activate
67+
2. **Config file** — edit `.gitmem/config.json` directly with `supabase_url`, `supabase_key`, `openrouter_key` fields
68+
3. **Interactive prompt** — if running in a terminal, activate will prompt for any missing values
69+
70+
## What gets created
71+
72+
The activate command creates these in your Supabase project:
73+
74+
| Tables | Purpose |
75+
|--------|---------|
76+
| `gitmem_learnings` | Scars, wins, patterns with embeddings |
77+
| `gitmem_sessions` | Session history and reflections |
78+
| `gitmem_decisions` | Decision log with rationale |
79+
| `gitmem_scar_usage` | Tracks when scars are surfaced and applied |
80+
| `gitmem_threads` | Cross-session work items |
81+
| `gitmem_query_metrics` | Performance tracking |
82+
| `knowledge_triples` | Knowledge graph relationships |
83+
| `scar_enforcement_variants` | A/B testing for scar delivery |
84+
85+
| Views | Purpose |
86+
|-------|---------|
87+
| `gitmem_learnings_lite` | Learnings without embedding column (fast reads) |
88+
| `gitmem_sessions_lite` | Sessions without embedding column |
89+
| `gitmem_decisions_lite` | Decisions without embedding column |
90+
| `gitmem_threads_lite` | Threads without embedding column |
91+
92+
| RPC Functions | Purpose |
93+
|---------------|---------|
94+
| `gitmem_semantic_search` | Vector similarity search across learnings |
95+
| `gitmem_scar_search` | Weighted search with temporal + behavioral decay |
96+
| `refresh_scar_behavioral_scores` | Updates decay weights from usage patterns |
97+
98+
All tables have Row Level Security enabled with service role access only.
99+
100+
## Pro tools
101+
102+
With pro activated, these tools persist to Supabase with semantic search:
103+
104+
| Tool | What it does |
105+
|------|-------------|
106+
| `session_start` | Loads context from last session, open threads, recent decisions |
107+
| `session_close` | Persists session reflection and learnings |
108+
| `recall` | Semantic search for relevant scars before taking action |
109+
| `create_learning` | Store a scar, win, or pattern with embedding |
110+
| `create_decision` | Log a decision with rationale |
111+
| `search` | Search institutional memory by keyword or semantics |
112+
| `log` | Browse recent learnings chronologically |
113+
| `create_thread` | Track unresolved work across sessions |
114+
| `list_threads` | View open threads |
115+
| `confirm_scars` | Acknowledge recalled scars before proceeding |
116+
117+
## Deactivation
118+
119+
```bash
120+
npx gitmem-mcp deactivate
121+
```
122+
123+
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.
124+
125+
## Troubleshooting
126+
127+
### Schema not applied automatically
128+
129+
If you see "Missing tables" after activation, the auto-schema needs a Supabase access token:
130+
131+
```bash
132+
npx supabase login # stores token locally
133+
npx gitmem-mcp activate # re-run, schema will auto-apply
134+
```
135+
136+
Or apply manually:
137+
138+
```bash
139+
npx gitmem-mcp setup | pbcopy # macOS — copies SQL to clipboard
140+
npx gitmem-mcp setup # prints SQL
141+
```
142+
143+
Then paste into Supabase Dashboard → SQL Editor → Run.
144+
145+
### Device limit reached
146+
147+
Each license allows 3 concurrent devices. Deactivate unused devices:
148+
149+
```bash
150+
npx gitmem-mcp deactivate # on the device you want to free
151+
```
152+
153+
### Connection test fails
154+
155+
Verify your `SUPABASE_URL` ends with `.supabase.co` and your service role key is the full JWT (starts with `eyJ`).
156+
157+
### Recall returns no results
158+
159+
Recall uses semantic search via embeddings. Make sure:
160+
- `OPENROUTER_API_KEY` is set (or `OPENAI_API_KEY`)
161+
- You've created at least one learning with `create_learning`
162+
- The learning has a description long enough to generate a meaningful embedding

0 commit comments

Comments
 (0)