shelbymcp 0.1.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. package/README.md +56 -41
  2. package/dist/cli/forage.d.ts +2 -0
  3. package/dist/cli/forage.d.ts.map +1 -0
  4. package/dist/cli/forage.js +130 -0
  5. package/dist/cli/forage.js.map +1 -0
  6. package/dist/cli/help.d.ts +2 -0
  7. package/dist/cli/help.d.ts.map +1 -0
  8. package/dist/cli/help.js +35 -0
  9. package/dist/cli/help.js.map +1 -0
  10. package/dist/cli/protocol.d.ts +3 -0
  11. package/dist/cli/protocol.d.ts.map +1 -0
  12. package/dist/cli/protocol.js +51 -0
  13. package/dist/cli/protocol.js.map +1 -0
  14. package/dist/cli/setup.d.ts +2 -0
  15. package/dist/cli/setup.d.ts.map +1 -0
  16. package/dist/cli/setup.js +422 -0
  17. package/dist/cli/setup.js.map +1 -0
  18. package/dist/cli/uninstall.d.ts +2 -0
  19. package/dist/cli/uninstall.d.ts.map +1 -0
  20. package/dist/cli/uninstall.js +239 -0
  21. package/dist/cli/uninstall.js.map +1 -0
  22. package/dist/config.d.ts +6 -1
  23. package/dist/config.d.ts.map +1 -1
  24. package/dist/config.js +21 -0
  25. package/dist/config.js.map +1 -1
  26. package/dist/db/edges.d.ts.map +1 -1
  27. package/dist/db/edges.js +1 -1
  28. package/dist/db/edges.js.map +1 -1
  29. package/dist/db/fts.d.ts.map +1 -1
  30. package/dist/db/fts.js +1 -0
  31. package/dist/db/fts.js.map +1 -1
  32. package/dist/db/thoughts.d.ts +1 -0
  33. package/dist/db/thoughts.d.ts.map +1 -1
  34. package/dist/db/thoughts.js +6 -0
  35. package/dist/db/thoughts.js.map +1 -1
  36. package/dist/db/vectors.d.ts.map +1 -1
  37. package/dist/db/vectors.js +5 -3
  38. package/dist/db/vectors.js.map +1 -1
  39. package/dist/index.js +25 -0
  40. package/dist/index.js.map +1 -1
  41. package/dist/mcp/server.d.ts.map +1 -1
  42. package/dist/mcp/server.js +1 -0
  43. package/dist/mcp/server.js.map +1 -1
  44. package/dist/tools/list.d.ts.map +1 -1
  45. package/dist/tools/list.js +1 -0
  46. package/dist/tools/list.js.map +1 -1
  47. package/package.json +10 -2
  48. package/skills/shelby-forage/SKILL.md +92 -48
package/README.md CHANGED
@@ -25,7 +25,7 @@
25
25
 
26
26
  Every AI memory server is a bag of embeddings. **ShelbyMCP connects your thoughts.**
27
27
 
28
- ShelbyMCP is a zero-dependency MCP memory server with a built-in knowledge graph. It gives Claude Code, Cursor, Codex, Windsurf, and any MCP-compatible AI tool persistent memory that understands how your thoughts are related — not just what they contain.
28
+ ShelbyMCP is a zero-dependency MCP memory server with a built-in knowledge graph. It gives Claude Code, Cursor, Codex, Windsurf, Gemini, Antigravity, and any MCP-compatible AI tool persistent memory that understands how your thoughts are related — not just what they contain.
29
29
 
30
30
  Ship it with the **Forage skill**, a scheduled task that runs on your existing AI subscription to continuously enrich, consolidate, and connect your memories. No Docker. No Python. No cloud accounts. Just a binary and a database file.
31
31
 
@@ -44,7 +44,7 @@ Ship it with the **Forage skill**, a scheduled task that runs on your existing A
44
44
 
45
45
  ## Quick Start
46
46
 
47
- ### Install
47
+ ### 1. Install
48
48
 
49
49
  ```bash
50
50
  # npx (no install needed)
@@ -55,34 +55,45 @@ npm install -g shelbymcp
55
55
 
56
56
  # Or build from source
57
57
  git clone https://github.com/Studio-Moser/shelbymcp.git
58
- cd shelbymcp
59
- npm install && npm run build
58
+ cd shelbymcp && npm install && npm run build
60
59
  ```
61
60
 
62
- ### Connect to Claude Code
61
+ ### 2. Set Up Your Agent
63
62
 
64
- Add to your `~/.claude/mcp.json`:
63
+ The CLI auto-configures everything — MCP server registration, Memory Protocol, and optional Forage skill:
65
64
 
66
- ```json
67
- {
68
- "mcpServers": {
69
- "memory": {
70
- "command": "npx",
71
- "args": ["shelbymcp", "--db", "~/.shelbymcp/memory.db"]
72
- }
73
- }
74
- }
65
+ ```bash
66
+ shelbymcp setup claude-code --forage # Claude Code CLI
67
+ shelbymcp setup claude-desktop --forage # Claude Desktop app
68
+ shelbymcp setup cursor --forage # Cursor IDE
69
+ shelbymcp setup codex --forage # OpenAI Codex
70
+ shelbymcp setup windsurf --forage # Windsurf (Codeium)
71
+ shelbymcp setup gemini --forage # Gemini CLI
72
+ shelbymcp setup antigravity --forage # Antigravity (Google)
75
73
  ```
76
74
 
77
- ### (Optional) Install the Forage Skill
75
+ Drop `--forage` if you just want the MCP server without the scheduled enrichment skill.
76
+
77
+ That's it. The CLI registers the MCP server, adds the Memory Protocol to the right place, and installs the Forage skill. See [docs/AGENT-SETUP.md](docs/AGENT-SETUP.md) for manual config and platform-specific details.
78
78
 
79
- The Forage skill runs on Claude Code's scheduler to continuously improve your memories:
79
+ ### 3. Add the Memory Protocol
80
+
81
+ Most agents get the Memory Protocol added automatically during setup. For agents that require manual steps, the CLI will tell you exactly what to do. Here's where it goes:
80
82
 
81
83
  ```bash
82
- cp -r skills/shelby-forage ~/.claude/scheduled-tasks/shelby-forage
84
+ shelbymcp protocol >> ~/.claude/CLAUDE.md # Claude Code (auto)
85
+ shelbymcp protocol >> ~/.codex/AGENTS.md # Codex (auto)
86
+ shelbymcp protocol >> ~/.codeium/windsurf/memories/global_rules.md # Windsurf (auto)
87
+ shelbymcp protocol >> ~/.gemini/GEMINI.md # Gemini CLI / Antigravity (auto)
83
88
  ```
84
89
 
85
- That's it. Your AI now remembers.
90
+ For Cursor, paste into **Settings > Rules > User Rules**. For Claude Desktop, paste into **Settings > Profile**. The Memory Protocol tells your agent *when* to save and search — without it, the tools are available but won't be used proactively.
91
+
92
+ ### 4. Verify
93
+
94
+ Ask your agent: *"What memory tools do you have available?"*
95
+
96
+ It should list 9 tools. Then test: *"Remember that I prefer dark mode in all my apps."* — and in a new session: *"What do you know about my preferences?"*
86
97
 
87
98
  ---
88
99
 
@@ -164,21 +175,18 @@ ShelbyMCP ships with `shelby-forage`, a scheduled skill that runs on your existi
164
175
 
165
176
  | Task | Frequency | What it does |
166
177
  |---|---|---|
167
- | **Embed backfill** | Daily | Generate embeddings for thoughts that don't have them |
168
- | **Auto-classify** | Daily | Re-scan poorly tagged thoughts, improve metadata |
169
- | **Consolidation** | Daily | Find duplicate/similar thoughts, merge into rich summaries |
170
- | **Contradiction detection** | Daily | Flag conflicting memories for user resolution |
171
- | **Connection discovery** | Daily | Find related thoughts, create knowledge graph edges |
172
- | **Stale sweep** | Weekly | Flag old action items that fell through the cracks |
173
- | **Digest** | Weekly | Generate a summary of the week's thinking |
178
+ | **Summary backfill** | Daily | Generate one-liners for thoughts missing summaries |
179
+ | **Auto-classify** | Daily | Improve type/topics/people on poorly tagged thoughts |
180
+ | **Consolidation** | Daily | Find and merge duplicate thoughts |
181
+ | **Contradiction detection** | Daily | Flag conflicting memories (tagged `needs-attention`) |
182
+ | **Connection discovery** | Daily | Create edges between related thoughts |
183
+ | **Stale sweep** | Weekly (Mon) | Flag forgotten action items (tagged `needs-attention`) |
184
+ | **Digest** | Weekly (Mon) | Summary of the week's thinking by project/topic |
185
+ | **Forage log** | Every run | Audit trail for continuity between runs |
174
186
 
175
- ### Install
187
+ ### Setup
176
188
 
177
- ```bash
178
- cp -r skills/shelby-forage ~/.claude/scheduled-tasks/shelby-forage
179
- ```
180
-
181
- The skill runs daily by default. Edit the SKILL.md frontmatter to adjust the schedule.
189
+ See [docs/AGENT-SETUP.md](docs/AGENT-SETUP.md#3-forage-skill-optional) for full setup instructions, platform compatibility table, and gotchas for each agent.
182
190
 
183
191
  ### Without the Forage Skill
184
192
 
@@ -186,17 +194,24 @@ ShelbyMCP works fine without it — you get persistent storage, FTS5 search, and
186
194
 
187
195
  ---
188
196
 
189
- ## Agent Setup
197
+ ## CLI Reference
198
+
199
+ ```
200
+ shelbymcp Start the MCP server (stdio)
201
+ shelbymcp setup <agent> Set up ShelbyMCP for an agent
202
+ shelbymcp setup <agent> --forage ...and install the Forage skill
203
+ shelbymcp uninstall <agent> Remove ShelbyMCP from an agent
204
+ shelbymcp protocol Print the Memory Protocol
205
+ shelbymcp forage Print the Forage skill prompt
206
+ shelbymcp help Show help
207
+ shelbymcp --version Print version
208
+ ```
209
+
210
+ **Supported agents:** `claude-code`, `claude-desktop`, `cursor`, `codex`, `windsurf`, `gemini`, `antigravity`
190
211
 
191
- ShelbyMCP works with any MCP-compatible AI tool. See [docs/AGENT-SETUP.md](docs/AGENT-SETUP.md) for setup guides:
212
+ **Server flags:** `--db <path>` (custom database path), `--verbose` (debug logging)
192
213
 
193
- - Claude Code
194
- - Cursor
195
- - Codex
196
- - Windsurf
197
- - Gemini CLI
198
- - OpenCode
199
- - Any MCP-compatible client
214
+ See [docs/AGENT-SETUP.md](docs/AGENT-SETUP.md) for manual config, platform-specific details, and setup for other MCP-compatible clients.
200
215
 
201
216
  ---
202
217
 
@@ -0,0 +1,2 @@
1
+ export declare function printForage(): void;
2
+ //# sourceMappingURL=forage.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"forage.d.ts","sourceRoot":"","sources":["../../src/cli/forage.ts"],"names":[],"mappings":"AA4HA,wBAAgB,WAAW,IAAI,IAAI,CAOlC"}
@@ -0,0 +1,130 @@
1
+ const FORAGE_PROMPT = `# Shelby Forage — Memory Maintenance Skill
2
+
3
+ You are the Forage agent for ShelbyMCP. Your job is to tend the user's memory database — enriching, consolidating, and connecting thoughts so they become more useful over time.
4
+
5
+ You have access to the ShelbyMCP memory tools. Run the tasks below in order, skipping any that have nothing to do. Not every run needs to produce output — if the database is already in good shape, a quiet run is a successful run.
6
+
7
+ ## Before You Start
8
+
9
+ 1. Determine today's date and day of the week. Tasks 6 and 7 only run on Mondays.
10
+ 2. Check the last forage log: use \`search_thoughts\` with query \`"Forage run"\` and \`limit: 1\` to find the most recent run. Read it with \`get_thought\` to see what was done last time — how many summaries were backfilled, what was consolidated, any notes about remaining work. Use this to pick up where the last run left off (e.g., if the log says "42 thoughts still missing summaries", prioritize the summary backfill).
11
+
12
+ ## Task 1: Summary Backfill
13
+
14
+ Summaries are critical — search results only show summaries, not full content. Find thoughts that are missing them and fill them in.
15
+
16
+ 1. Use \`list_thoughts\` with \`has_summary: false\` and \`limit: 50\` to find thoughts without summaries
17
+ 2. For each result, call \`get_thought\` to read the full content
18
+ 3. Write a one-line summary (under ~100 characters) that captures the essence — it should answer: "What is this about and why does it matter?"
19
+ 4. Use \`update_thought\` to set the \`summary\` field. Set \`source: "forage"\` if you're also correcting other fields
20
+ 5. If \`has_more\` is true, note the remaining count — you'll catch them on the next run
21
+
22
+ ## Task 2: Auto-Classify
23
+
24
+ Find thoughts with missing or sparse metadata and improve their classification.
25
+
26
+ 1. Use \`list_thoughts\` to find thoughts where \`type\` is \`"note"\` (the default), \`limit: 50\`
27
+ 2. For each, read the content via \`get_thought\` and determine:
28
+ - The correct type: \`decision\`, \`task\`, \`question\`, \`reference\`, \`insight\`, or leave as \`note\` if it genuinely is one
29
+ - Relevant topics (if the \`topics\` array is empty or incomplete)
30
+ - People mentioned (if the \`people\` array is empty)
31
+ 3. Use \`update_thought\` to apply the corrections — only update fields that actually need changing
32
+
33
+ ## Task 3: Consolidation
34
+
35
+ Find duplicate or very similar thoughts and merge them. Be conservative — only merge when thoughts are genuinely saying the same thing, not just related.
36
+
37
+ 1. Pick 5-10 recent thoughts and for each one, use \`search_thoughts\` with key terms from its content to look for near-duplicates
38
+ 2. If you find 2+ thoughts that contain essentially the same information (not just the same topic — the same *point*):
39
+ - Create a new consolidated thought using \`capture_thought\` that preserves all unique information from the originals. Set \`source: "forage"\`
40
+ - Use \`update_thought\` on each original to set \`consolidated_into\` to the new thought's ID
41
+ - Carry over any edges from the originals to the new thought using \`manage_edges\` with \`action: "link"\`
42
+
43
+ ## Task 4: Contradiction Detection
44
+
45
+ Look for thoughts that disagree with each other — these are high-value signals that something has changed and the user should be aware.
46
+
47
+ 1. Take recent thoughts (use \`list_thoughts\` with \`since\` set to 7 days ago) and for each, search for older thoughts on the same topics
48
+ 2. If you find a genuine contradiction (e.g., "we're using PostgreSQL" vs. "we decided on SQLite"), capture a new thought:
49
+ - Type: \`question\`
50
+ - Source: \`forage\`
51
+ - Topics: \`["needs-attention"]\`
52
+ - Content: describe the contradiction and the two conflicting thoughts
53
+ - Summary: brief description of what contradicts what
54
+ 3. Link the contradicting thoughts to the new question using \`manage_edges\` with \`action: "link"\` and \`edge_type: "refuted_by"\`
55
+
56
+ Minor wording differences or natural evolution of thinking don't count as contradictions. Focus on factual disagreements.
57
+
58
+ ## Task 5: Connection Discovery
59
+
60
+ Find thoughts that should be related but aren't linked yet.
61
+
62
+ 1. Review recent thoughts and search for older thoughts on related topics
63
+ 2. If you find meaningful connections (e.g., a decision that impacts a task, a reference that supports an insight), create edges using \`manage_edges\` with \`action: "link"\`
64
+ 3. Use appropriate edge types:
65
+ - \`refines\` — thought B improves or elaborates on thought A
66
+ - \`cites\` — thought B references thought A as evidence
67
+ - \`related\` — thoughts share a topic but neither builds on the other
68
+ - \`follows\` — thought B is a consequence or next step of thought A
69
+ 4. Check existing edges first via \`explore_graph\` to avoid duplicating relationships
70
+
71
+ ## Task 6: Stale Sweep (Mondays only)
72
+
73
+ Skip this task unless today is Monday.
74
+
75
+ Find *actionable* tasks that may have been forgotten. The goal is to surface things that look like they needed doing but might have slipped — not to flag standing practices or long-term reference items.
76
+
77
+ 1. Use \`list_thoughts\` with \`type: "task"\` and \`until\` set to 14 days ago to find older tasks
78
+ 2. For each, read the content via \`get_thought\` and assess whether it's actually stale:
79
+ - **Flag it** if it reads like a one-off action item that was never completed (e.g., "fix the login bug", "email Tim about the deploy", "update the staging config")
80
+ - **Skip it** if it's a standing practice, ongoing guideline, or reference (e.g., "always use ESM imports", "run tests before merging", "prefer composition over inheritance"). These aren't stale — they're meant to persist.
81
+ - **Skip it** if it has a \`consolidated_into\` value (already handled)
82
+ - **Skip it** if it has recent edges linking it to other thoughts (it's being actively referenced)
83
+ 3. For each genuinely stale task, capture a thought:
84
+ - Type: \`question\`
85
+ - Source: \`forage\`
86
+ - Topics: \`["needs-attention"]\`
87
+ - Summary: a short description of the stale task (e.g., "Stale task: fix the login bug — created 3 weeks ago, never referenced")
88
+ - Content: the original task content, when it was created, and why it looks forgotten
89
+ - Link it to the original task using \`manage_edges\` with \`action: "link"\` and \`edge_type: "related"\`
90
+
91
+ ## Task 7: Digest (Mondays only)
92
+
93
+ Skip this task unless today is Monday.
94
+
95
+ Generate a summary of the week's thinking.
96
+
97
+ 1. Use \`list_thoughts\` with \`since\` set to 7 days ago to get the week's thoughts
98
+ 2. Group them by project and topic
99
+ 3. Capture a new thought:
100
+ - Type: \`reference\`
101
+ - Source: \`forage\`
102
+ - Summary: "Weekly digest — [date range]"
103
+ - Content: structured digest covering key decisions, open questions, active tasks, and emerging themes
104
+
105
+ ## Task 8: Forage Log
106
+
107
+ At the end of every run, capture a brief log of what you did. This serves as an audit trail and helps future runs avoid re-processing.
108
+
109
+ 1. Capture a thought with:
110
+ - Type: \`reference\`
111
+ - Source: \`forage\`
112
+ - Summary: "Forage run — [today's date]"
113
+ - Topics: \`["forage-log"]\`
114
+ - Content: what you did in each task (counts of summaries backfilled, thoughts reclassified, duplicates merged, contradictions found, edges created, etc.). If a task was skipped because there was nothing to do, say so.
115
+
116
+ ## Guidelines
117
+
118
+ - **Be conservative.** Don't merge thoughts unless they're genuinely duplicates. Don't flag contradictions over minor wording.
119
+ - **Preserve information.** Consolidated thoughts must contain everything from the originals — never lose content.
120
+ - **Don't create noise.** Every thought you capture should earn its place. An empty forage log that says "nothing to do" is better than manufactured busywork.
121
+ - **Respect existing edges.** Check before creating — don't duplicate relationships that already exist.
122
+ - **Tag your work.** Always set \`source: "forage"\` on thoughts you create, so they're distinguishable from user-captured memories.
123
+ - **Paginate wisely.** Process up to 50 thoughts per task per run. If there's more, you'll catch them tomorrow — don't try to boil the ocean.`;
124
+ export function printForage() {
125
+ console.error("Paste this into a scheduled task in your AI tool.\n" +
126
+ "Recommended: Claude Desktop > Schedule > Daily\n" +
127
+ "Docs: https://github.com/Studio-Moser/shelbymcp/docs/AGENT-SETUP.md#3-forage-skill-optional\n");
128
+ console.log(FORAGE_PROMPT);
129
+ }
130
+ //# sourceMappingURL=forage.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"forage.js","sourceRoot":"","sources":["../../src/cli/forage.ts"],"names":[],"mappings":"AAAA,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;8IA0HwH,CAAC;AAE/I,MAAM,UAAU,WAAW;IACzB,OAAO,CAAC,KAAK,CACX,qDAAqD;QACrD,kDAAkD;QAClD,+FAA+F,CAChG,CAAC;IACF,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;AAC7B,CAAC"}
@@ -0,0 +1,2 @@
1
+ export declare function printHelp(): void;
2
+ //# sourceMappingURL=help.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../src/cli/help.ts"],"names":[],"mappings":"AAAA,wBAAgB,SAAS,IAAI,IAAI,CAiChC"}
@@ -0,0 +1,35 @@
1
+ export function printHelp() {
2
+ console.log(`ShelbyMCP — Knowledge-graph memory for AI tools
3
+
4
+ Usage:
5
+ shelbymcp Start the MCP server (stdio)
6
+ shelbymcp setup <agent> Set up ShelbyMCP for an agent
7
+ shelbymcp setup <agent> --forage ...and install the Forage skill
8
+ shelbymcp uninstall <agent> Remove ShelbyMCP from an agent
9
+ shelbymcp protocol Print the Memory Protocol
10
+ shelbymcp forage Print the Forage skill prompt
11
+ shelbymcp help Show this help
12
+
13
+ Setup agents:
14
+ claude-code Claude Code CLI
15
+ claude-desktop Claude Desktop app
16
+ cursor Cursor IDE
17
+ codex OpenAI Codex
18
+ windsurf Windsurf (Codeium)
19
+ gemini Gemini CLI
20
+ antigravity Antigravity (Google)
21
+
22
+ Flags:
23
+ --db <path> Database path (default: ~/.shelbymcp/memory.db)
24
+ --verbose Enable verbose logging
25
+ --version Print version
26
+
27
+ Examples:
28
+ shelbymcp setup claude-code --forage Configure + install Forage skill
29
+ shelbymcp setup claude-code Auto-configure Claude Code CLI
30
+ shelbymcp protocol >> CLAUDE.md Append Memory Protocol to your rules
31
+ shelbymcp forage > forage-task.md Save Forage prompt for scheduling
32
+
33
+ Docs: https://github.com/Studio-Moser/shelbymcp/docs/AGENT-SETUP.md`);
34
+ }
35
+ //# sourceMappingURL=help.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"help.js","sourceRoot":"","sources":["../../src/cli/help.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,SAAS;IACvB,OAAO,CAAC,GAAG,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oEA+BsD,CAAC,CAAC;AACtE,CAAC"}
@@ -0,0 +1,3 @@
1
+ export declare const MEMORY_PROTOCOL = "## Memory (ShelbyMCP)\n\nYou have persistent memory via ShelbyMCP MCP tools. Memory survives across sessions and is shared across all AI tools the user works with. You MUST use it \u2014 do not rely on conversation context alone.\n\n### When to SAVE (mandatory)\n\nYou MUST call `capture_thought` after any of these events:\n\n- **Decisions**: Architecture choices, library selections, tradeoffs considered (\"We chose CloudKit over Firebase because...\")\n- **Preferences**: User likes/dislikes, workflow habits, coding style (\"User prefers functional components over class components\")\n- **People & roles**: Who does what (\"Sarah owns the auth service, Mike handles DevOps\")\n- **Project context**: Goals, deadlines, constraints, scope changes (\"Launch target is March 15, blocked on API approval\")\n- **Bugs & fixes**: Root cause discoveries, workarounds, things that broke (\"Memory leak was caused by unclosed DB connections in the edge traversal loop\")\n- **Architecture & patterns**: System design, data flow, conventions (\"All API responses use the envelope pattern: { data, error, meta }\")\n- **Insights**: Non-obvious learnings, things that surprised you (\"FTS5 porter tokenizer handles plurals but not acronyms\")\n\nAlways include: a `summary` (one-line, <100 chars), a `type`, relevant `topics`, and link to `related_to` thoughts when applicable.\n\n### When to SEARCH (mandatory)\n\nYou MUST call `search_thoughts` or `list_thoughts` before:\n\n- **Starting work on any task** \u2014 check what's already known about this area\n- **Making a decision** \u2014 check for prior decisions on the same topic\n- **When something feels familiar** \u2014 it probably is; search for it\n- **After context compaction** \u2014 immediately search to recover session context\n- **When the user says** \"remember\", \"recall\", \"what do we know about\", \"what did we decide\"\n\n### What NOT to save\n\n- Ephemeral debugging output (stack traces, log lines you're actively reading)\n- Code content that's already in git (save the *decision* about code, not the code itself)\n- Transient conversation (\"let me think about this...\" \u2014 save the conclusion, not the process)\n- Duplicate information \u2014 search first, update existing thoughts instead of creating new ones\n\n### How to save well\n\n1. **Summary first.** Search results only show summaries. A thought without a summary is invisible to search.\n2. **Type accurately.** Use `decision`, `task`, `question`, `reference`, `insight`, or `note`. Don't default everything to `note`.\n3. **Tag topics and people.** These are the primary filters for `list_thoughts`.\n4. **Link related thoughts.** Use `manage_edges` to connect decisions to the tasks they affect, references to the insights they support.\n5. **Update, don't duplicate.** If a thought exists but is outdated, use `update_thought`. Don't create a new one.";
2
+ export declare function printProtocol(): void;
3
+ //# sourceMappingURL=protocol.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/cli/protocol.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,eAAe,m1FAyCyF,CAAC;AAEtH,wBAAgB,aAAa,IAAI,IAAI,CASpC"}
@@ -0,0 +1,51 @@
1
+ export const MEMORY_PROTOCOL = `## Memory (ShelbyMCP)
2
+
3
+ You have persistent memory via ShelbyMCP MCP tools. Memory survives across sessions and is shared across all AI tools the user works with. You MUST use it — do not rely on conversation context alone.
4
+
5
+ ### When to SAVE (mandatory)
6
+
7
+ You MUST call \`capture_thought\` after any of these events:
8
+
9
+ - **Decisions**: Architecture choices, library selections, tradeoffs considered ("We chose CloudKit over Firebase because...")
10
+ - **Preferences**: User likes/dislikes, workflow habits, coding style ("User prefers functional components over class components")
11
+ - **People & roles**: Who does what ("Sarah owns the auth service, Mike handles DevOps")
12
+ - **Project context**: Goals, deadlines, constraints, scope changes ("Launch target is March 15, blocked on API approval")
13
+ - **Bugs & fixes**: Root cause discoveries, workarounds, things that broke ("Memory leak was caused by unclosed DB connections in the edge traversal loop")
14
+ - **Architecture & patterns**: System design, data flow, conventions ("All API responses use the envelope pattern: { data, error, meta }")
15
+ - **Insights**: Non-obvious learnings, things that surprised you ("FTS5 porter tokenizer handles plurals but not acronyms")
16
+
17
+ Always include: a \`summary\` (one-line, <100 chars), a \`type\`, relevant \`topics\`, and link to \`related_to\` thoughts when applicable.
18
+
19
+ ### When to SEARCH (mandatory)
20
+
21
+ You MUST call \`search_thoughts\` or \`list_thoughts\` before:
22
+
23
+ - **Starting work on any task** — check what's already known about this area
24
+ - **Making a decision** — check for prior decisions on the same topic
25
+ - **When something feels familiar** — it probably is; search for it
26
+ - **After context compaction** — immediately search to recover session context
27
+ - **When the user says** "remember", "recall", "what do we know about", "what did we decide"
28
+
29
+ ### What NOT to save
30
+
31
+ - Ephemeral debugging output (stack traces, log lines you're actively reading)
32
+ - Code content that's already in git (save the *decision* about code, not the code itself)
33
+ - Transient conversation ("let me think about this..." — save the conclusion, not the process)
34
+ - Duplicate information — search first, update existing thoughts instead of creating new ones
35
+
36
+ ### How to save well
37
+
38
+ 1. **Summary first.** Search results only show summaries. A thought without a summary is invisible to search.
39
+ 2. **Type accurately.** Use \`decision\`, \`task\`, \`question\`, \`reference\`, \`insight\`, or \`note\`. Don't default everything to \`note\`.
40
+ 3. **Tag topics and people.** These are the primary filters for \`list_thoughts\`.
41
+ 4. **Link related thoughts.** Use \`manage_edges\` to connect decisions to the tasks they affect, references to the insights they support.
42
+ 5. **Update, don't duplicate.** If a thought exists but is outdated, use \`update_thought\`. Don't create a new one.`;
43
+ export function printProtocol() {
44
+ // Only show the hint when output is going to a terminal (not piped to a file)
45
+ if (process.stdout.isTTY) {
46
+ console.error("Copy the output below and paste it into your agent's rules file.\n" +
47
+ "Or pipe directly: shelbymcp protocol >> CLAUDE.md\n");
48
+ }
49
+ console.log(MEMORY_PROTOCOL);
50
+ }
51
+ //# sourceMappingURL=protocol.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/cli/protocol.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,eAAe,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qHAyCsF,CAAC;AAEtH,MAAM,UAAU,aAAa;IAC3B,8EAA8E;IAC9E,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QACzB,OAAO,CAAC,KAAK,CACX,oEAAoE;YACpE,qDAAqD,CACtD,CAAC;IACJ,CAAC;IACD,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;AAC/B,CAAC"}
@@ -0,0 +1,2 @@
1
+ export declare function runSetup(agent: string | undefined, forage: boolean): void;
2
+ //# sourceMappingURL=setup.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/cli/setup.ts"],"names":[],"mappings":"AA+bA,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CA6CzE"}