@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

npm install @baixfeng/agent-memory

Or use it directly as a binary:

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

# 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:

{
  "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:

{
  "query": "javascript closures",
  "page": 1,
  "limit": 10,
  "category": "Programming"
}

Response:

{
  "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:

{
  "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:

{
  "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:

{
  "ids": [1, 2, 3]
}

---

6. list_categories

List all unique categories from stored memories.

Parameters: None

Returns: JSON object with array of categories

Response:

{
  "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:

{
  "page": 1,
  "limit": 10,
  "category": "Programming",
  "sort_by": "updated_at",
  "sort_order": "desc"
}

Response:

{
  "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

git clone https://github.com/baiXfeng/agent-memory.git
cd agent-memory

Install Dependencies

npm install

Build

npm run build

Development Mode

npm run dev

Start Server

npm start

Database Schema

Main Table: memories

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:

{
  "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:

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