npm package: @mootmcp/server
Description: Self-hosted long-term memory MCP server for AI assistants
Author: archlinuxusa
Latest version: 0.1.0

# Moot

Self-hosted long-term memory MCP server for AI assistants. Your memories, your data, your control.

[![npm version](https://badge.fury.io/js/@mootmcp%2Fserver.svg)](https://www.npmjs.com/package/@mootmcp/server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## How It Works

```
~/.moot/memories.db     ← Central database (all memories)
     │
     ├── Project: "myapp"      ← Linked via /Projects/MyApp/.moot
     ├── Project: "blog"       ← Linked via /Projects/Blog/.moot
     └── (global memories)     ← Not scoped to any project
```

When you work in a directory with a `.moot` file, all memories are automatically scoped to that project. Global memories (preferences, general knowledge) are always accessible.

## Installation

### Via npm (recommended)

```bash
npm install -g @mootmcp/server
```

### From source

```bash
git clone https://github.com/archlinuxusa/moot.git
cd moot
npm install
npm run build
```

> **Note:** This package uses `better-sqlite3` which includes pre-built binaries for most platforms. If installation fails, you may need build tools installed (Python, C++ compiler).

## Setup

### 1. Add to your MCP client config

**For Claude Code** (`~/.claude/settings.json` or project `.mcp.json`):

```json
{
  "mcpServers": {
    "moot": {
      "command": "moot"
    }
  }
}
```

**For Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "moot": {
      "command": "npx",
      "args": ["-y", "@mootmcp/server"]
    }
  }
}
```

### 2. Initialize a project

In any project directory, run `init_project` to create a `.moot` file:

```
/Projects/MyApp/
├── .moot              ← Created by init_project
├── src/
└── package.json
```

The `.moot` file links that directory to a project in the database:

```json
{
  "project": "MyApp",
  "created": "2024-01-16T..."
}
```

## Tools

| Tool | Description |
|------|-------------|
| `init_project` | Create `.moot` file to link directory to a project |
| `project_status` | Show current project and memory stats |
| `save_memory` | Save content (auto-scoped to current project) |
| `recall` | Search memories (project + global) |
| `forget` | Remove memories by ID or search query |
| `list_memories` | List all memories with pagination |

## Usage Examples

**Initialize a project:**
```
→ init_project({ name: "my-cool-app" })
Creates .moot file, all future memories scoped to "my-cool-app"
```

**Save a memory:**
```
→ save_memory({ content: "User prefers Tailwind over vanilla CSS" })
Saved to project "my-cool-app"

→ save_memory({ content: "User's name is Chris", global: true })
Saved as global (accessible in all projects)
```

**Recall memories:**
```
→ recall({ query: "CSS preferences" })
Searches "my-cool-app" + global memories
```

## Data Storage

- **Database:** `~/.moot/memories.db` (SQLite)
- **Project files:** `.moot` in each project directory

## Future Plans

- Semantic search with local embeddings
- Web dashboard at moot.christopherallen.dev
- Memory decay/importance over time
- Export/import tools

## License

MIT