Content
# @baixfeng/agent-memory
A powerful MCP (Model Context Protocol) server providing persistent memory storage with full-text search capabilities. Built with SQLite and FTS5 (Full-Text Search), it enables AI assistants to store, retrieve, and manage knowledge locally with efficient fuzzy search.
## Features
- **Persistent Storage**: SQLite-based local database with automatic backups
- **Full-Text Search**: FTS5 with trigram tokenization for fuzzy matching
- **Memory Management**: Complete CRUD operations (Create, Read, Update, Delete)
- **Categorization**: Organize memories by custom categories
- **Keyword System**: Tag memories with searchable keywords
- **Pagination**: Efficient search results with configurable page size
- **Debug Logging**: Optional file-based logging for troubleshooting
- **WAL Mode**: Write-Ahead Logging for better concurrent access
## Installation
```bash
npm install @baixfeng/agent-memory
```
Or use it directly as a binary:
```bash
npx @baixfeng/agent-memory [storage-dir] [enable-log]
```
## Configuration
The server accepts two optional command-line arguments:
### 1. Storage Directory
- **Default**: `~/.local-memory`
- **Usage**: Specify a custom directory for storing the database and logs
- **Example**: `/custom/path/to/memory` or `~/my-memory`
### 2. Enable Log File
- **Default**: `false`
- **Usage**: Pass `"true"` to enable file-based logging
- **Note**: Debug output is always sent to stderr (visible in MCP Inspector)
- **Example**: `true`
### Example Usage
```bash
# Default configuration
agent-memory
# Custom storage directory
agent-memory /path/to/memory
# Custom storage with logging
agent-memory /path/to/memory true
```
## MCP Tools
The server provides the following MCP tools:
### 1. save_memory
Save a new piece of knowledge to the memory database.
**Parameters**:
- `title` (string): Short title for the memory
- `summary` (string): Brief summary of the content
- `content` (string): Full content/body of the memory
- `keywords` (array of strings): List of searchable keywords
- `category` (string): Category for organizing the memory
**Returns**: Memory ID of the saved record
**Example**:
```json
{
"title": "JavaScript Closures",
"summary": "Understanding how closures work in JavaScript",
"content": "Closures allow functions to access variables from their outer scope...",
"keywords": ["javascript", "closures", "scope"],
"category": "Programming"
}
```
---
### 2. search_memories
Search through stored memories using full-text search.
**Parameters**:
- `query` (string): Search keywords or phrase
- `page` (number, optional): Page number (default: 1)
- `limit` (number, optional): Results per page (default: 25, max: 100)
- `category` (string, optional): Filter results by category
**Returns**: JSON object with pagination info and memory metadata
**Example**:
```json
{
"query": "javascript closures",
"page": 1,
"limit": 10,
"category": "Programming"
}
```
**Response**:
```json
{
"page": 1,
"limit": 10,
"results": [
{
"id": 1,
"title": "JavaScript Closures",
"summary": "Understanding how closures work in JavaScript",
"keywords": ["javascript", "closures", "scope"],
"category": "Programming",
"date": "2024-01-15"
}
]
}
```
---
### 3. read_memory
Read the full content of a specific memory by ID.
**Parameters**:
- `id` (number): Memory ID to retrieve
**Returns**: Complete memory record with full content
**Example**:
```json
{
"id": 1
}
```
---
### 4. update_memory
Update existing memory fields.
**Parameters**:
- `id` (number): Memory ID to update
- `title` (string, optional): New title
- `summary` (string, optional): New summary
- `content` (string, optional): New content
- `keywords` (array of strings, optional): New keywords
- `category` (string, optional): New category
**Returns**: Success message
**Example**:
```json
{
"id": 1,
"title": "Updated Title",
"summary": "Updated summary",
"keywords": ["javascript", "updated"]
}
```
---
### 5. delete_memory
Delete one or more memories by their IDs.
**Parameters**:
- `ids` (array of numbers): List of memory IDs to delete
**Returns**: Confirmation message with count of deleted records
**Example**:
```json
{
"ids": [1, 2, 3]
}
```
---
### 6. list_categories
List all unique categories from stored memories.
**Parameters**: None
**Returns**: JSON object with array of categories
**Response**:
```json
{
"categories": ["Programming", "Design", "Documentation"]
}
```
---
### 7. list_memories
List memories metadata with pagination, category filtering, and sorting.
**Parameters**:
- `page` (number, optional): Page number (default: 1)
- `limit` (number, optional): Results per page (default: 25, max: 100)
- `category` (string, optional): Filter memories by category
- `sort_by` (string, optional): Sort field - `created_at` or `updated_at` (default: `updated_at`)
- `sort_order` (string, optional): Sort order - `desc` or `asc` (default: `desc`)
**Returns**: JSON object with pagination info and memory metadata
**Example**:
```json
{
"page": 1,
"limit": 10,
"category": "Programming",
"sort_by": "updated_at",
"sort_order": "desc"
}
```
**Response**:
```json
{
"page": 1,
"limit": 10,
"total_count": 847,
"total_pages": 85,
"results": [
{
"id": 1,
"title": "JavaScript Closures",
"summary": "Understanding how closures work in JavaScript",
"keywords": ["javascript", "closures", "scope"],
"category": "Programming",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-20T15:45:00Z"
}
]
}
```
## Development
### Prerequisites
- Node.js >= 18.0.0
- npm or yarn
### Clone the Repository
```bash
git clone https://github.com/baiXfeng/agent-memory.git
cd agent-memory
```
### Install Dependencies
```bash
npm install
```
### Build
```bash
npm run build
```
### Development Mode
```bash
npm run dev
```
### Start Server
```bash
npm start
```
## Database Schema
### Main Table: `memories`
```sql
CREATE TABLE memories (
id INTEGER PRIMARY KEY AUTOINCREMENT,
title TEXT NOT NULL,
summary TEXT NOT NULL,
content TEXT NOT NULL,
keywords TEXT,
category TEXT,
created_at TEXT DEFAULT CURRENT_TIMESTAMP,
updated_at TEXT DEFAULT CURRENT_TIMESTAMP
)
```
### Full-Text Search Table: `memories_fts`
Uses FTS5 with trigram tokenization for efficient fuzzy search across all text fields.
## File Structure
```
~/.local-memory/ # Default storage directory
├── memory.db # Main SQLite database
├── memory.db.bak # Automatic backup (created on startup)
└── debug.log # Debug log (if enabled)
```
## MCP Configuration
To use this server with an MCP client (like Claude Desktop), add it to your MCP configuration file:
### Claude Desktop (macOS)
Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"memory": {
"command": "node",
"args": ["/path/to/node_modules/@baixfeng/agent-memory/dist/index.js", "/custom/path", "true"]
}
}
}
```
## Troubleshooting
### Debug Logging
Enable file-based logging by passing `"true"` as the second argument:
```bash
agent-memory /path/to/storage true
```
Logs will be written to `<storage-dir>/debug.log`.
### Common Issues
1. **Database locked errors**: Ensure no other process is using the database
2. **Permission denied**: Check write permissions for the storage directory
3. **Search returns no results**: Try broader query terms or check FTS5 index status
## Performance
- **FTS5 Search**: Optimized with trigram tokenization for fuzzy matching
- **WAL Mode**: Supports concurrent reads and writes
- **Pagination**: Limits memory usage for large result sets
- **Automatic Indexes**: Triggers keep full-text index synchronized
## License
MIT License - see LICENSE file for details
## Contributing
Contributions are welcome! Please feel free to submit issues or pull requests.
## Author
**renzynx**
## Repository
https://github.com/baiXfeng/agent-memory
