# @renzynx/memory-mcp

A persistent memory MCP server with FTS5 fuzzy search. Compatible with Bun and Node.js.

## Features

- **Persistent Storage**: Data stored in `~/.mcp-memory/memory.db` survives npx/bunx cache clears
- **Fuzzy Search**: FTS5 with trigram tokenization for substring matching (`pyth` → `python`)
- **Token Efficient**: Results in TOON format for minimal token usage
- **Auto Maintenance**: Prunes entries older than 30 days, creates backups on startup
- **Cross Runtime**: Works with both Bun and Node.js

## Installation

```bash
npx @renzynx/memory-mcp
# or
bunx @renzynx/memory-mcp
```

## Configuration

### OpenCode

Add to `~/.config/opencode/opencode.jsonc`:

```jsonc
{
  "mcp": {
    "memory": {
      "type": "local",
      "command": ["bunx", "@renzynx/memory-mcp"]
    }
  }
}
```

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["@renzynx/memory-mcp"]
    }
  }
}
```

## Tools

### save_memory

Store information with a category.

```
save_memory(content: string, category: string)
```

**Categories**: `preferences`, `facts`, `context`, `projects`, `conventions`

### search_memories

Fuzzy search stored memories. Returns TOON format or `Ø` if empty.

```
search_memories(query: string)
```

### list_categories

List all unique categories. Returns TOON format or `Ø` if empty.

```
list_categories()
```

## Agent Instructions

Add to your agent system prompt:

```
## Memory System

You have access to a persistent memory system via MCP tools. Use it proactively to remember important information across sessions.

### Tools Available
- `save_memory(content, category)` - Store information with a category
- `search_memories(query)` - Fuzzy search (supports partial matches like "pyth" → "python")
- `list_categories()` - View all memory categories

### When to Save Memories
- User preferences (coding style, tools, frameworks, communication preferences)
- Project context (architecture decisions, file structures, conventions)
- Facts about the user (name, role, team, timezone)
- Recurring tasks or workflows
- Corrections or clarifications the user provides
- Important decisions and their rationale

### Categories to Use
- `preferences` - User preferences and settings
- `facts` - Information about the user or their environment
- `projects` - Project-specific context and decisions
- `conventions` - Coding standards and patterns
- `context` - Session or task context worth preserving

### When to Search Memories
- At the start of conversations to recall user context
- Before making assumptions about preferences
- When the user references something previously discussed
- Before suggesting tools, patterns, or approaches

### Output Format
Results return in TOON format for token efficiency. "Ø" means no results found.

### Best Practices
- Save incrementally, not everything at once
- Use specific, searchable content
- Search before asking the user to repeat themselves
- Update memories when information changes (save new version)
```

## License

MIT