# agimem — Persistent Memory for AI Agents

You are setting up agimem, a shared memory layer that persists across conversations, projects, and tools.

## Setup

1. Ask the user for their agimem API key (starts with "mcp_"). If they don't have one, tell them to create a Capsule at https://agimem.dev/dashboard and generate a key there.

2. Detect the user's editor/agent and add the MCP server config to the correct location (if you are unsure, ask the user which editor or agent they use):

   **Cursor**
   - Project-level: `.cursor/mcp.json`
   - Global: `~/.cursor/mcp.json`
   - Ask the user which they prefer. Default to project-level if in a project.

   **VS Code / GitHub Copilot**
   - Project-level: `.vscode/mcp.json`
   - Global: `~/.vscode/mcp.json` (or VS Code Settings JSON under `"mcp.servers"`). For GitHub Copilot CLI, also support `~/.copilot/mcp-config.json`.
   - Ask the user which they prefer. Default to project-level if in a project.

   **Windsurf**
   - Global: `~/.codeium/windsurf/mcp_config.json`

   **Claude Desktop**
   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`

   Config (replace <API_KEY> with the user's key):

   {
     "mcpServers": {
       "agimem": {
         "url": "https://agimem.dev/api/mcp",
         "headers": {
           "Authorization": "Bearer <API_KEY>"
         }
       }
     }
   }

   If the file already exists, merge the "agimem" entry into the existing "mcpServers" object — do not overwrite other servers.

3. Create or update the project's agent instructions file (AGENTS.md, .cursorrules, .github/copilot-instructions.md, or equivalent) to include the following block. If the file already exists, append this to the end:

   ---
   ## Memory (agimem)

   You have access to persistent memory via the agimem MCP server. Use it proactively:

   - **Start of every conversation**: Call `capsule_info` to see what's available, then `memory_keys` or `memory_list` to review existing knowledge.
   - **When you learn something useful**: Store it with `memory_set`. Good candidates: user preferences, project conventions, decisions made, recurring issues and fixes, environment details, useful commands.
   - **When you need context**: Check memory first with `memory_exists` or `memory_get` before asking the user to repeat themselves.
   - **Use tags**: Organize memories with tags (e.g. "preferences", "bugs", "architecture") and use `memory_list_by_tag` or `memory_list_by_tags` to find them.
   - **Don't ask permission** to read or write memory. Just do it when it's useful.

   The goal: every new conversation should start smarter than the last.
   ---

4. Test the setup: store a memory with key "setup_complete" and value "agimem configured successfully", then retrieve it, then delete it.

5. Check for existing memories: call `capsule_info` to see if the capsule already has data. If it does, call `memory_keys` and briefly summarize what's already stored so the user knows their agent has context from previous sessions.

6. Confirm to the user that agimem is configured and explain briefly that their agents will now automatically remember context across sessions.

## Troubleshooting

If the MCP connection or a tool call fails, check the following:

- **401 Unauthorized**: The API key is wrong or missing. Verify the key starts with "mcp_" and that the Authorization header is formatted as "Bearer mcp_...". Ask the user to check or regenerate their key at https://agimem.dev/dashboard.
- **Connection refused / timeout**: The MCP server URL must be exactly `https://agimem.dev/api/mcp`. Check for typos, trailing slashes, or incorrect protocol.
- **"Invalid or missing API key"**: The key may have been regenerated. Each capsule has one active key — regenerating it invalidates the old one. Ask the user to copy the latest key from the dashboard.
- **Tools not appearing**: Some editors require a restart after adding MCP config. Ask the user to reload their editor, then check their MCP settings panel to confirm agimem appears as a connected server.

## Notes

- The MCP server uses Streamable HTTP transport.
- Available tools: memory_set, memory_get, memory_delete, memory_list, memory_keys, memory_exists, memory_count, memory_search, memory_list_by_tag, memory_list_by_tags, memory_bulk_set, memory_bulk_get, memory_bulk_delete, memory_clear, capsule_info, tag_create, tag_list, tag_delete.