# @mnemonik/scanner

Automatic codebase indexing daemon for [Mnemonik](https://mnemonik.ai) — persistent memory for AI coding assistants.

The scanner watches your project directories for code changes and indexes them so your AI assistant can find relevant files, functions, and patterns when you need them.

## Installation

```bash
npm install -g @mnemonik/scanner
```

## Quick Start

```bash
mnemonik-scanner start --key <your-api-key> --roots ~/Projects
```

Your API key is available on the [Mnemonik dashboard](https://app.mnemonik.ai). The `--roots` flag specifies which directories to scan for projects (comma-separated).

Configuration is saved to `~/.mnemonik/scanner.json` after first run. Subsequent starts need no arguments:

```bash
mnemonik-scanner start
```

## How It Works

1. The daemon walks your `--roots` directories looking for `.mnemonik.json` files (created automatically by your IDE's Mnemonik integration)
2. For each discovered project, it scans source files and pushes code chunks to the Mnemonik API
3. It watches for file changes and incrementally updates the index
4. Every 5 minutes, it re-scans roots to discover new projects, handle folder renames, and drop deleted projects

### Watched is not registered

Every directory under your roots is **watched** (walked). Only a directory with
a usable `.mnemonik.json` is **registered**, and only a registered project is
ever scanned or indexed. The two numbers differ whenever a checkout under a
root has no config file, so the daemon reports them separately:

```
[scanner] Watching 15 directories: 13 registered and scanned, 2 watched but unregistered (no usable .mnemonik.json — not scanned)
```

Each unregistered directory is named once, with the `.mnemonik.json` it is
missing, and `mnemonik-scanner doctor` lists them under the
`watched dirs are registered` check. Nothing is registered automatically —
whether a directory should be indexed is your decision. Register one by running
`session_bootstrap` with that directory as `cwd` (it writes `.mnemonik.json`),
or drop it from your roots.

## Commands

| Command | Description |
|---------|-------------|
| `mnemonik-scanner start [options]` | Start the daemon |
| `mnemonik-scanner stop` | Stop the running daemon |
| `mnemonik-scanner status` | Show daemon status and watched projects |
| `mnemonik-scanner log` | Show recent log output |
| `mnemonik-scanner doctor` | Check install health (drift detection) |
| `mnemonik-scanner help` | Show usage information |

### Start Options

| Option | Description |
|--------|-------------|
| `--key <api-key>` | Mnemonik API key (or set `MNEMONIK_API_KEY` env var) |
| `--server <url>` | Server URL (default: `https://api.mnemonik.dev`) |
| `--roots <dirs>` | Comma-separated directories to scan for projects |

## Configuration

The daemon saves its configuration to `~/.mnemonik/scanner.json` with `0600` permissions (owner read/write only).

You can also set the API key via the `MNEMONIK_API_KEY` environment variable, which takes precedence over the config file and is never written to disk.

### Files

| Path | Purpose |
|------|---------|
| `~/.mnemonik/scanner.json` | Persistent configuration |
| `~/.mnemonik/daemon.pid` | PID file for the running daemon |
| `~/.mnemonik/scanner.log` | Log file (rotated at 5MB) |

## What Gets Indexed

The scanner indexes code chunks (functions, classes, modules) from these file types:

`.ts` `.tsx` `.js` `.jsx` `.py` `.rs` `.go` `.java` `.c` `.cpp` `.h` `.cs` `.rb` `.php` `.swift` `.kt` `.md`

It skips common directories and files (`node_modules`, `.git`, `dist`, `build`, lock files, bundled/minified assets, etc.) using Mnemonik's built-in ignore patterns. Only code structure is indexed — binary files and non-code assets are ignored.

## Resource Usage

The daemon is designed to run continuously with minimal impact:

- **CPU**: Event-driven (idle when no files change)
- **Disk**: Log rotation at 5MB
- **Network**: Only changed files are pushed (hash-based diffing)

## Requirements

- Node.js 20 or later
- A Mnemonik account and API key ([sign up](https://mnemonik.ai))

## License

Proprietary. See [mnemonik.ai/terms](https://mnemonik.ai/terms) for details.