mirror of
https://github.com/samvallad33/vestige.git
synced 2026-04-25 00:36:22 +02:00
feat: v2.0 distribution — IDE integrations, zero-config installer, README overhaul
- Add integration guides for Xcode 26.3, Cursor, VS Code, JetBrains, Windsurf - First cognitive memory server with documented Xcode 26.3 MCP support - Add npx @vestige/init — zero-config CLI that auto-detects IDEs and injects config - Overhaul README: "The open-source cognitive engine for AI" - Add "Why Not Just Use RAG?" comparison and cognitive science stack docs - Update license badge to AGPL-3.0
This commit is contained in:
Sam Valladares
parent
04a3062328
commit
3fce1f0b70
8 changed files with 1378 additions and 92 deletions
142
docs/integrations/cursor.md
Normal file
142
docs/integrations/cursor.md
Normal file
|
|
@ -0,0 +1,142 @@
|
|||
# Cursor
|
||||
|
||||
> Give Cursor a brain that remembers between sessions.
|
||||
|
||||
Cursor has native MCP support. Add Vestige and your AI assistant remembers your architecture, preferences, and past fixes across every session.
|
||||
|
||||
---
|
||||
|
||||
## Setup
|
||||
|
||||
### 1. Create or edit the config file
|
||||
|
||||
**Global (all projects):**
|
||||
|
||||
| Platform | Path |
|
||||
|----------|------|
|
||||
| macOS / Linux | `~/.cursor/mcp.json` |
|
||||
| Windows | `%USERPROFILE%\.cursor\mcp.json` |
|
||||
|
||||
```bash
|
||||
# macOS / Linux
|
||||
mkdir -p ~/.cursor
|
||||
open -e ~/.cursor/mcp.json
|
||||
```
|
||||
|
||||
### 2. Add Vestige
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"vestige": {
|
||||
"command": "/usr/local/bin/vestige-mcp",
|
||||
"args": [],
|
||||
"env": {}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> **Use absolute paths.** Cursor does not reliably resolve relative paths or `~`. Run `which vestige-mcp` to find your binary location.
|
||||
|
||||
**Windows:**
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"vestige": {
|
||||
"command": "C:\\Users\\you\\.cargo\\bin\\vestige-mcp.exe",
|
||||
"args": [],
|
||||
"env": {}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Restart Cursor
|
||||
|
||||
Fully quit and reopen Cursor. The MCP server loads on startup.
|
||||
|
||||
### 4. Verify
|
||||
|
||||
Open Cursor's AI chat and ask:
|
||||
|
||||
> "What MCP tools do you have access to?"
|
||||
|
||||
You should see Vestige's tools listed (search, smart_ingest, memory, etc.).
|
||||
|
||||
---
|
||||
|
||||
## First Use
|
||||
|
||||
Ask Cursor's AI:
|
||||
|
||||
> "Remember that this project uses React with TypeScript and Tailwind CSS"
|
||||
|
||||
Start a **new chat session**, then:
|
||||
|
||||
> "What tech stack does this project use?"
|
||||
|
||||
It remembers.
|
||||
|
||||
---
|
||||
|
||||
## Project-Specific Memory
|
||||
|
||||
To isolate memory per project, use `--data-dir`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"vestige": {
|
||||
"command": "/usr/local/bin/vestige-mcp",
|
||||
"args": ["--data-dir", "/Users/you/projects/my-app/.vestige"],
|
||||
"env": {}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Or place a `.cursor/mcp.json` in the project root for project-level config.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
<details>
|
||||
<summary>Vestige tools not appearing</summary>
|
||||
|
||||
1. Verify the binary exists:
|
||||
```bash
|
||||
which vestige-mcp
|
||||
```
|
||||
2. Test the binary manually:
|
||||
```bash
|
||||
echo '{}' | vestige-mcp
|
||||
```
|
||||
3. Check the config is valid JSON:
|
||||
```bash
|
||||
cat ~/.cursor/mcp.json | python3 -m json.tool
|
||||
```
|
||||
4. Fully restart Cursor (Cmd+Q / Alt+F4, not just close window).
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>Silent failures</summary>
|
||||
|
||||
Cursor does not surface MCP server errors in the UI. Test by running the command directly in your terminal to see actual error output.
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## Also Works With
|
||||
|
||||
| IDE | Guide |
|
||||
|-----|-------|
|
||||
| Xcode 26.3 | [Setup](./xcode.md) |
|
||||
| VS Code (Copilot) | [Setup](./vscode.md) |
|
||||
| JetBrains | [Setup](./jetbrains.md) |
|
||||
| Windsurf | [Setup](./windsurf.md) |
|
||||
| Claude Code | [Setup](../CONFIGURATION.md#claude-code-one-liner) |
|
||||
| Claude Desktop | [Setup](../CONFIGURATION.md#claude-desktop-macos) |
|
||||
|
||||
Your AI remembers everything, everywhere.
|
||||
129
docs/integrations/jetbrains.md
Normal file
129
docs/integrations/jetbrains.md
Normal file
|
|
@ -0,0 +1,129 @@
|
|||
# JetBrains (IntelliJ, WebStorm, PyCharm, etc.)
|
||||
|
||||
> Give your JetBrains AI assistant a brain that remembers.
|
||||
|
||||
JetBrains IDEs (2025.2+) have built-in MCP support. Vestige integrates through the MCP server settings, giving your AI assistant persistent memory across sessions.
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **JetBrains IDE 2025.2+** (IntelliJ IDEA, WebStorm, PyCharm, GoLand, etc.)
|
||||
- **vestige-mcp** binary installed ([Installation guide](../../README.md#quick-start))
|
||||
|
||||
---
|
||||
|
||||
## Setup
|
||||
|
||||
### Option A: Auto-Configure (Recommended)
|
||||
|
||||
JetBrains can auto-configure MCP servers for connected clients:
|
||||
|
||||
1. Open **Settings** (`Cmd+,` / `Ctrl+Alt+S`)
|
||||
2. Navigate to **Tools > MCP Server**
|
||||
3. Click **"+"** to add a new MCP server
|
||||
4. Configure:
|
||||
- **Name:** `vestige`
|
||||
- **Command:** `/usr/local/bin/vestige-mcp`
|
||||
- **Arguments:** (leave empty)
|
||||
5. Click **Apply**
|
||||
|
||||
### Option B: Junie AI Config
|
||||
|
||||
If using JetBrains Junie AI, add Vestige to the Junie MCP config:
|
||||
|
||||
**User-level (all projects):**
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.junie/mcp
|
||||
```
|
||||
|
||||
Edit `~/.junie/mcp/mcp.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"vestige": {
|
||||
"command": "/usr/local/bin/vestige-mcp",
|
||||
"args": [],
|
||||
"env": {}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Project-level:**
|
||||
|
||||
Create `.junie/mcp/mcp.json` in your project root with the same format.
|
||||
|
||||
### Option C: Via External Client
|
||||
|
||||
JetBrains exposes its own tools via MCP. You can also use Vestige through an external client (Claude Code, Cursor) that connects to JetBrains:
|
||||
|
||||
1. In JetBrains: **Settings > Tools > MCP Server**
|
||||
2. Click **Auto-Configure** for your preferred client
|
||||
3. Add Vestige to that client's config (see [Cursor](./cursor.md), [VS Code](./vscode.md))
|
||||
|
||||
---
|
||||
|
||||
## Verify
|
||||
|
||||
After configuration, the MCP server should appear in **Settings > Tools > MCP Server** with a green status indicator.
|
||||
|
||||
Test by asking your AI assistant:
|
||||
|
||||
> "Remember that this project uses Spring Boot with Kotlin and follows hexagonal architecture"
|
||||
|
||||
---
|
||||
|
||||
## Project-Specific Memory
|
||||
|
||||
Isolate memory per project:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"vestige": {
|
||||
"command": "/usr/local/bin/vestige-mcp",
|
||||
"args": ["--data-dir", "/Users/you/projects/my-app/.vestige"],
|
||||
"env": {}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
<details>
|
||||
<summary>MCP server not appearing in settings</summary>
|
||||
|
||||
1. Verify your IDE version is 2025.2 or later.
|
||||
2. Check that the binary path is absolute:
|
||||
```bash
|
||||
which vestige-mcp
|
||||
```
|
||||
3. Restart the IDE after adding the configuration.
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>Finding your client's config file</summary>
|
||||
|
||||
In **Settings > Tools > MCP Server**, click the expansion arrow next to your client, then select **"Open Client Settings File"** to see the exact config path.
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## Also Works With
|
||||
|
||||
| IDE | Guide |
|
||||
|-----|-------|
|
||||
| Xcode 26.3 | [Setup](./xcode.md) |
|
||||
| Cursor | [Setup](./cursor.md) |
|
||||
| VS Code (Copilot) | [Setup](./vscode.md) |
|
||||
| Windsurf | [Setup](./windsurf.md) |
|
||||
| Claude Code | [Setup](../CONFIGURATION.md#claude-code-one-liner) |
|
||||
| Claude Desktop | [Setup](../CONFIGURATION.md#claude-desktop-macos) |
|
||||
|
||||
Your AI remembers everything, everywhere.
|
||||
160
docs/integrations/vscode.md
Normal file
160
docs/integrations/vscode.md
Normal file
|
|
@ -0,0 +1,160 @@
|
|||
# VS Code (GitHub Copilot)
|
||||
|
||||
> Give Copilot a brain that remembers between sessions.
|
||||
|
||||
VS Code supports MCP servers through GitHub Copilot's agent mode. Vestige plugs directly in, giving Copilot persistent memory across every coding session.
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **VS Code 1.99+** (or latest stable)
|
||||
- **GitHub Copilot** extension installed and active
|
||||
- **vestige-mcp** binary installed ([Installation guide](../../README.md#quick-start))
|
||||
|
||||
---
|
||||
|
||||
## Setup
|
||||
|
||||
### 1. Create the config file
|
||||
|
||||
**Workspace (recommended — shareable with team):**
|
||||
|
||||
Create `.vscode/mcp.json` in your project root:
|
||||
|
||||
```bash
|
||||
mkdir -p .vscode
|
||||
```
|
||||
|
||||
**User-level (all projects):**
|
||||
|
||||
Open Command Palette (`Cmd+Shift+P`) and run:
|
||||
|
||||
```
|
||||
MCP: Open User Configuration
|
||||
```
|
||||
|
||||
### 2. Add Vestige
|
||||
|
||||
Note: VS Code uses `"servers"` (not `"mcpServers"`).
|
||||
|
||||
```json
|
||||
{
|
||||
"servers": {
|
||||
"vestige": {
|
||||
"command": "/usr/local/bin/vestige-mcp",
|
||||
"args": [],
|
||||
"env": {}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> **Use absolute paths.** Run `which vestige-mcp` to find your binary.
|
||||
|
||||
**Windows:**
|
||||
```json
|
||||
{
|
||||
"servers": {
|
||||
"vestige": {
|
||||
"command": "C:\\Users\\you\\.cargo\\bin\\vestige-mcp.exe",
|
||||
"args": [],
|
||||
"env": {}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Verify
|
||||
|
||||
VS Code auto-detects config changes — no restart needed.
|
||||
|
||||
Open **Copilot Chat** (agent mode) and ask:
|
||||
|
||||
> "What MCP tools do you have?"
|
||||
|
||||
Vestige's tools (search, smart_ingest, memory, etc.) should appear.
|
||||
|
||||
---
|
||||
|
||||
## First Use
|
||||
|
||||
In Copilot Chat:
|
||||
|
||||
> "Remember that this project uses Express.js with PostgreSQL and follows REST conventions"
|
||||
|
||||
Start a **new chat**, then:
|
||||
|
||||
> "What's the tech stack for this project?"
|
||||
|
||||
It remembers.
|
||||
|
||||
---
|
||||
|
||||
## Secure API Keys (Optional)
|
||||
|
||||
VS Code supports input variables to avoid hardcoding secrets:
|
||||
|
||||
```json
|
||||
{
|
||||
"inputs": [
|
||||
{
|
||||
"type": "promptString",
|
||||
"id": "vestige-data-dir",
|
||||
"description": "Vestige data directory"
|
||||
}
|
||||
],
|
||||
"servers": {
|
||||
"vestige": {
|
||||
"command": "/usr/local/bin/vestige-mcp",
|
||||
"args": ["--data-dir", "${input:vestige-data-dir}"],
|
||||
"env": {}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Share Memory Config With Your Team
|
||||
|
||||
Since `.vscode/mcp.json` lives in the project, you can commit it:
|
||||
|
||||
```bash
|
||||
git add .vscode/mcp.json
|
||||
git commit -m "Add Vestige memory server for Copilot"
|
||||
```
|
||||
|
||||
Every team member with Vestige installed will automatically get memory-enabled Copilot.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
<details>
|
||||
<summary>Vestige not showing in Copilot</summary>
|
||||
|
||||
1. Ensure you're using **agent mode** in Copilot Chat (not inline completions).
|
||||
2. Verify VS Code version is 1.99+.
|
||||
3. Check the config file is at `.vscode/mcp.json` (not `.vscode/settings.json`).
|
||||
4. Verify the key is `"servers"` not `"mcpServers"`.
|
||||
5. Test the binary manually:
|
||||
```bash
|
||||
which vestige-mcp && echo "Found" || echo "Not found"
|
||||
```
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## Also Works With
|
||||
|
||||
| IDE | Guide |
|
||||
|-----|-------|
|
||||
| Xcode 26.3 | [Setup](./xcode.md) |
|
||||
| Cursor | [Setup](./cursor.md) |
|
||||
| JetBrains | [Setup](./jetbrains.md) |
|
||||
| Windsurf | [Setup](./windsurf.md) |
|
||||
| Claude Code | [Setup](../CONFIGURATION.md#claude-code-one-liner) |
|
||||
| Claude Desktop | [Setup](../CONFIGURATION.md#claude-desktop-macos) |
|
||||
|
||||
Your AI remembers everything, everywhere.
|
||||
155
docs/integrations/windsurf.md
Normal file
155
docs/integrations/windsurf.md
Normal file
|
|
@ -0,0 +1,155 @@
|
|||
# Windsurf
|
||||
|
||||
> Give Cascade a brain that remembers between sessions.
|
||||
|
||||
Windsurf has native MCP support through its Cascade AI. Add Vestige and Cascade remembers your architecture, preferences, and past decisions across every session.
|
||||
|
||||
---
|
||||
|
||||
## Setup
|
||||
|
||||
### 1. Open the config file
|
||||
|
||||
**Option A — Via UI:**
|
||||
|
||||
1. Open **Windsurf > Settings > Advanced Settings**
|
||||
2. Scroll to the **"Cascade"** section
|
||||
3. Click **"view the raw JSON config file"**
|
||||
|
||||
**Option B — Direct path:**
|
||||
|
||||
| Platform | Path |
|
||||
|----------|------|
|
||||
| macOS / Linux | `~/.codeium/windsurf/mcp_config.json` |
|
||||
| Windows | `%USERPROFILE%\.codeium\windsurf\mcp_config.json` |
|
||||
|
||||
```bash
|
||||
# macOS / Linux
|
||||
open -e ~/.codeium/windsurf/mcp_config.json
|
||||
```
|
||||
|
||||
### 2. Add Vestige
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"vestige": {
|
||||
"command": "/usr/local/bin/vestige-mcp",
|
||||
"args": [],
|
||||
"env": {}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**With environment variable expansion** (Windsurf-specific feature):
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"vestige": {
|
||||
"command": "${env:HOME}/.cargo/bin/vestige-mcp",
|
||||
"args": [],
|
||||
"env": {}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Windows:**
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"vestige": {
|
||||
"command": "C:\\Users\\you\\.cargo\\bin\\vestige-mcp.exe",
|
||||
"args": [],
|
||||
"env": {}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Restart Windsurf
|
||||
|
||||
Restart the IDE or refresh the Cascade panel.
|
||||
|
||||
### 4. Verify
|
||||
|
||||
Open Cascade and ask:
|
||||
|
||||
> "What MCP tools do you have?"
|
||||
|
||||
You should see Vestige's tools listed.
|
||||
|
||||
---
|
||||
|
||||
## First Use
|
||||
|
||||
In Cascade:
|
||||
|
||||
> "Remember that this project uses Next.js 15 with the App Router and Drizzle ORM"
|
||||
|
||||
Start a **new Cascade session**, then:
|
||||
|
||||
> "What framework does this project use?"
|
||||
|
||||
It remembers.
|
||||
|
||||
---
|
||||
|
||||
## Project-Specific Memory
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"vestige": {
|
||||
"command": "/usr/local/bin/vestige-mcp",
|
||||
"args": ["--data-dir", "${env:HOME}/projects/my-app/.vestige"],
|
||||
"env": {}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Important: Tool Limit
|
||||
|
||||
Windsurf has a **hard cap of 100 tools** across all MCP servers. Vestige uses ~19 tools, leaving plenty of room for other servers.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
<details>
|
||||
<summary>Vestige not appearing in Cascade</summary>
|
||||
|
||||
1. Verify the config file is valid JSON:
|
||||
```bash
|
||||
cat ~/.codeium/windsurf/mcp_config.json | python3 -m json.tool
|
||||
```
|
||||
2. Ensure you're using absolute paths (or `${env:HOME}` expansion).
|
||||
3. Check the Cascade panel for error messages.
|
||||
4. Fully restart Windsurf.
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>Tool limit exceeded</summary>
|
||||
|
||||
If you have many MCP servers and exceed 100 total tools, Cascade will ignore excess servers. Remove unused servers or use Vestige's unified tools (each handles multiple operations).
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## Also Works With
|
||||
|
||||
| IDE | Guide |
|
||||
|-----|-------|
|
||||
| Xcode 26.3 | [Setup](./xcode.md) |
|
||||
| Cursor | [Setup](./cursor.md) |
|
||||
| VS Code (Copilot) | [Setup](./vscode.md) |
|
||||
| JetBrains | [Setup](./jetbrains.md) |
|
||||
| Claude Code | [Setup](../CONFIGURATION.md#claude-code-one-liner) |
|
||||
| Claude Desktop | [Setup](../CONFIGURATION.md#claude-desktop-macos) |
|
||||
|
||||
Your AI remembers everything, everywhere.
|
||||
260
docs/integrations/xcode.md
Normal file
260
docs/integrations/xcode.md
Normal file
|
|
@ -0,0 +1,260 @@
|
|||
# Xcode 26.3
|
||||
|
||||
> Give Apple Intelligence a brain that remembers.
|
||||
|
||||
Xcode 26.3 supports [agentic coding](https://developer.apple.com/documentation/xcode/giving-agentic-coding-tools-access-to-xcode) with full MCP (Model Context Protocol) integration. Vestige plugs directly into Xcode's Claude Agent, giving it persistent memory across every coding session.
|
||||
|
||||
**Vestige is the first cognitive memory server for Xcode.**
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **Xcode 26.3** or later (Release Candidate or stable)
|
||||
- **vestige-mcp** binary installed ([Installation guide](../../README.md#quick-start))
|
||||
|
||||
Verify Vestige is installed:
|
||||
|
||||
```bash
|
||||
which vestige-mcp
|
||||
# Should output: /usr/local/bin/vestige-mcp
|
||||
```
|
||||
|
||||
If you installed to a different location, note the **absolute path** — you'll need it below.
|
||||
|
||||
---
|
||||
|
||||
## Setup
|
||||
|
||||
### 1. Open the config file
|
||||
|
||||
Xcode's Claude Agent reads MCP configuration from:
|
||||
|
||||
```
|
||||
~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/.claude
|
||||
```
|
||||
|
||||
Create or edit this file:
|
||||
|
||||
```bash
|
||||
mkdir -p ~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig
|
||||
open -e ~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/.claude
|
||||
```
|
||||
|
||||
### 2. Add Vestige
|
||||
|
||||
Paste the following configuration:
|
||||
|
||||
```json
|
||||
{
|
||||
"projects": {
|
||||
"*": {
|
||||
"mcpServers": {
|
||||
"vestige": {
|
||||
"type": "stdio",
|
||||
"command": "/usr/local/bin/vestige-mcp",
|
||||
"args": [],
|
||||
"env": {
|
||||
"PATH": "/usr/local/bin:/usr/bin:/bin"
|
||||
}
|
||||
}
|
||||
},
|
||||
"hasTrustDialogAccepted": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> **Important:** Xcode runs agents in a sandboxed environment that does **not** inherit your shell configuration (`.zshrc`, `.bashrc`, etc.). You **must** use absolute paths for the `command` field and explicitly set `PATH` in the `env` block.
|
||||
|
||||
#### Project-specific memory
|
||||
|
||||
To give each project its own isolated memory, use `--data-dir`:
|
||||
|
||||
```json
|
||||
{
|
||||
"projects": {
|
||||
"/Users/you/Developer/MyApp": {
|
||||
"mcpServers": {
|
||||
"vestige": {
|
||||
"type": "stdio",
|
||||
"command": "/usr/local/bin/vestige-mcp",
|
||||
"args": ["--data-dir", "/Users/you/Developer/MyApp/.vestige"],
|
||||
"env": {
|
||||
"PATH": "/usr/local/bin:/usr/bin:/bin"
|
||||
}
|
||||
}
|
||||
},
|
||||
"hasTrustDialogAccepted": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Restart Xcode
|
||||
|
||||
Quit and reopen Xcode. The Claude Agent will now load Vestige on startup.
|
||||
|
||||
### 4. Verify
|
||||
|
||||
In Xcode's Agent panel, type:
|
||||
|
||||
```
|
||||
/context
|
||||
```
|
||||
|
||||
You should see `vestige` listed as an available MCP server with its tools (search, smart_ingest, memory, etc.).
|
||||
|
||||
---
|
||||
|
||||
## First Use
|
||||
|
||||
Open any project and ask the Claude Agent:
|
||||
|
||||
> "Remember that this project uses SwiftUI with MVVM architecture and targets iOS 18+"
|
||||
|
||||
Start a **new session**, then ask:
|
||||
|
||||
> "What architecture does this project use?"
|
||||
|
||||
It remembers.
|
||||
|
||||
---
|
||||
|
||||
## What Vestige Does for Xcode
|
||||
|
||||
| Without Vestige | With Vestige |
|
||||
|-----------------|--------------|
|
||||
| Every session starts from zero | Agent recalls your architecture, patterns, and preferences |
|
||||
| Re-explain SwiftUI conventions each time | Agent knows your conventions from day one |
|
||||
| Bug fixes are forgotten | Agent remembers past fixes and avoids regressions |
|
||||
| No context between Xcode and other IDEs | Shared memory across Xcode, Cursor, VS Code, and more |
|
||||
|
||||
### Example Workflows
|
||||
|
||||
**Architecture decisions:**
|
||||
> "Remember: we chose Observation framework over Combine for state management because it's simpler and Apple-recommended for iOS 17+."
|
||||
|
||||
**Bug documentation:**
|
||||
> The agent fixes a Core Data migration crash? Vestige automatically stores the fix. Next time it encounters a migration issue, it remembers the solution.
|
||||
|
||||
**Cross-IDE memory:**
|
||||
> Fix a backend bug in VS Code. Open the iOS app in Xcode. The agent already knows about the API change because Vestige shares memory across all your tools.
|
||||
|
||||
---
|
||||
|
||||
## Tips
|
||||
|
||||
### Use a CLAUDE.md for proactive memory
|
||||
|
||||
Place a `CLAUDE.md` in your project root to make the agent use Vestige automatically:
|
||||
|
||||
```markdown
|
||||
## Memory
|
||||
|
||||
At the start of every session:
|
||||
1. Search Vestige for this project's context
|
||||
2. Recall architecture decisions and coding patterns
|
||||
3. Save important decisions and bug fixes without being asked
|
||||
```
|
||||
|
||||
See [CLAUDE.md templates](../CLAUDE-SETUP.md) for a full setup.
|
||||
|
||||
### Embedding model cache
|
||||
|
||||
The first time Vestige runs, it downloads the Nomic embedding model (~130MB). In Xcode's sandboxed environment, the cache location is:
|
||||
|
||||
```
|
||||
~/Library/Caches/com.vestige.core/fastembed
|
||||
```
|
||||
|
||||
If the download fails behind a corporate proxy, pre-download by running `vestige-mcp` once from your terminal before using it in Xcode.
|
||||
|
||||
### Skills integration
|
||||
|
||||
You can add Vestige-related skills to Xcode's skills directory:
|
||||
|
||||
```
|
||||
~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/skills/
|
||||
```
|
||||
|
||||
Drop a markdown file describing how the agent should use memory for your iOS/macOS projects.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
<details>
|
||||
<summary>"vestige" not showing in /context</summary>
|
||||
|
||||
1. Verify the binary path is correct and absolute:
|
||||
```bash
|
||||
ls -la /usr/local/bin/vestige-mcp
|
||||
```
|
||||
|
||||
2. Check that the config file is valid JSON:
|
||||
```bash
|
||||
cat ~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/.claude | python3 -m json.tool
|
||||
```
|
||||
|
||||
3. Ensure you fully quit and restarted Xcode (Cmd+Q, not just close window).
|
||||
|
||||
4. Check Xcode's agent logs for errors:
|
||||
```bash
|
||||
log show --predicate 'subsystem == "com.apple.dt.Xcode"' --last 5m | grep -i mcp
|
||||
```
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>Agent can't find vestige-mcp binary</summary>
|
||||
|
||||
Xcode's sandbox does not inherit your shell PATH. Use the full absolute path:
|
||||
|
||||
```json
|
||||
"command": "/usr/local/bin/vestige-mcp"
|
||||
```
|
||||
|
||||
If you installed via `cargo build`, the binary is likely at:
|
||||
```
|
||||
/Users/you/.cargo/bin/vestige-mcp
|
||||
```
|
||||
|
||||
Or wherever you copied it. Run `which vestige-mcp` in your terminal to find it.
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>Embedding model fails to download</summary>
|
||||
|
||||
The first run downloads ~130MB. If Xcode's sandbox blocks the download:
|
||||
|
||||
1. Run `vestige-mcp` once from your terminal to cache the model
|
||||
2. The cache at `~/Library/Caches/com.vestige.core/fastembed` will be available to the sandboxed instance
|
||||
|
||||
Behind a proxy:
|
||||
```bash
|
||||
HTTPS_PROXY=your-proxy:port vestige-mcp
|
||||
```
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## Also Works With
|
||||
|
||||
Vestige uses the MCP standard — the same memory works across all your tools:
|
||||
|
||||
| IDE | Guide |
|
||||
|-----|-------|
|
||||
| Claude Code | [Setup](../CONFIGURATION.md#claude-code-one-liner) |
|
||||
| Claude Desktop | [Setup](../CONFIGURATION.md#claude-desktop-macos) |
|
||||
| Cursor | [Setup](./cursor.md) |
|
||||
| VS Code (Copilot) | [Setup](./vscode.md) |
|
||||
| JetBrains | [Setup](./jetbrains.md) |
|
||||
| Windsurf | [Setup](./windsurf.md) |
|
||||
|
||||
Your AI remembers everything, everywhere.
|
||||
|
||||
---
|
||||
|
||||
<p align="center">
|
||||
<a href="../../README.md">Back to README</a>
|
||||
</p>
|
||||
Loading…
Add table
Add a link
Reference in a new issue