Memlink is a self-hosted MCP (Model Context Protocol) server that gives AI agents persistent, organized memory. One memory, one URL, any agent connects.

Installation

Standalone binary (recommended, no runtime required)

Linux / macOS:

curl -fsSL https://raw.githubusercontent.com/rblez/memlink/main/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/rblez/memlink/main/install.ps1 | iex

Binaries are available for linux/amd64, linux/arm64, darwin/amd64, darwin/arm64, and windows/amd64. See releases.

npm

npm install -g @memlink/cli   # or pnpm / yarn / bun

Requires Node 18+ (or Bun).

From source

git clone https://github.com/rblez/memlink.git
cd memlink
bun install
npm run build

Quick Start

memlink                                # System overview
memlink add "First note" "Hello world"  # Write to default memory
memlink entries                        # List entries
memlink search "hello"                 # Search entries
memlink serve --daemon                 # Start MCP server in background
memlink url                            # Show MCP config for your agent

Connect an AI agent

flowchart LR
    A[memlink serve --daemon] --> B[memlink url]
    B --> C[Copy MCP config JSON]
    C --> D{Which agent?}
    D -->|Claude Desktop| E[claude_desktop_config.json]
    D -->|Cursor| F[Cursor MCP settings]
    D -->|Windsurf| G[~/.codeium/windsurf/mcp_config.json]
    D -->|Other| H[Custom MCP client]
    E --> I[Restart agent]
    F --> I
    G --> I
    H --> I
    I --> J[Agent calls memory_read<br/>on session start]
    J --> K[Memlink serves entries<br/>from default memory]

Run the server

memlink serve --daemon

Same on Linux, macOS, and Windows. Runs as long as your session is active (or until memlink stop).

Commands

| Command | Description | |---------|-------------| | memlink add "<title>" "<content>" | Write entry to default memory (--tags, --memory) | | memlink entries | List entries in default memory (--memory, --limit) | | memlink search <query> | Search entries by title/tags (--memory, --limit) | | memlink url | Show MCP config JSON for the agent | | memlink token [list\|revoke] | Manage memory tokens | | memlink pause --memory <name> | Suspend a memory in the daemon | | memlink resume --memory <name> | Resume a paused memory | | memlink stop [--memory <name>] | Stop daemon (or remove a memory) | | memlink serve | Start MCP server (--port, --host, --daemon, --memory) | | memlink status | Daemon + memory stats | | memlink info <name\|id> | Memory details | | memlink delete <name\|id> | Permanently delete a memory | | memlink export [name\|id] | Export to .md / .json / .txt | | memlink import <name\|id> <file> | Import entries from JSON | | memlink config | View or modify config (get, set) | | memlink skill | Install agent skill (use --global for all projects) |

Documentation

| Document | Description | |----------|-------------| | Installation | All install methods + daemon setup | | Quick Start | Get running in 2 minutes | | CLI Reference | All commands and flags | | MCP Server | Server config, auth, transports | | MCP Tools | All MCP tool details | | Agent Setup | Connect Claude, Cursor, Windsurf, etc. | | Skill | Agent skill installation | | Backups | Backup and restore | | Architecture | How it works |

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | MEMLINK_DIR | Data directory | ~/.memlink | | MEMLINK_PORT / PORT | Server port | 4444 | | MEMLINK_HOST / HOST | Server host | localhost | | MEMLINK_NO_REPORT | Opt out of anonymous install reports | unset |

MCP Tools

| Tool | Description | Params | |------|-------------|--------| | memory_read | Read index or specific entry | id?, title?, full? | | memory_edit | Create or update an entry | title, content, tags? | | memory_search | Search by query | query | | memory_sync | Memory stats (count, size, last updated) | — |

Agents connect via:

http://localhost:4444/mcp?t=<TOKEN>      # named memory
http://localhost:4444/mcp                 # default memory

Architecture

~/.memlink/
├── settings.json              # Global config
├── default/                   # Default memory (auto-created)
│   ├── meta.json
│   ├── index.json
│   ├── 1.md, 2.md, ...        # Entries with YAML frontmatter
│   └── .backups/
├── my-project/                # Named memory
│   └── ...

Robustness

• Atomic writes: files written to .tmp then renamed
• Auto-backups: every edit creates a backup in .backups/
• File lock: concurrent writes serialized via .lock with TTL + retry
• Token routing: in-memory Map<token, MemoryRoute> (no IPC)
• Health ticker: 30s heartbeat in .health
• TTY detection: ASCII art disabled in non-TTY (CI, Docker)

Development

bun install              # Install deps
npm run build            # Build + typecheck
npm run dev:server       # Server with hot reload
npm run dev:cli          # CLI dev mode
npm run test             # Run tests
npm run lint             # ESLint
npm run format           # Prettier

Project Structure

src/
├── cli/index.ts        # CLI entrypoint (commander)
├── cli/output.ts       # Output formatting, colors, branding, skill template
├── cli/admin.ts        # CLI client for daemon admin API
├── server/index.ts     # MCP server (Express + @modelcontextprotocol/sdk)
├── core/
│   ├── storage.ts      # .md entries with YAML frontmatter, atomic writes
│   ├── meta.ts         # Per-memory meta.json CRUD, status tracking
│   ├── routing.ts      # Token → MemoryRoute map
│   ├── health.ts       # .health heartbeat
│   ├── auth.ts         # Local token (admin API)
│   ├── lock.ts         # .lock with TTL + withLock helper
│   ├── memory.ts       # Legacy CRUD, CLI helpers, config
│   └── types.ts        # Types, constants, getMemlinkDir
tests/
├── memory.test.ts      # Core memory unit tests
├── server.test.ts      # MCP server integration tests
└── unit.test.ts        # Edge cases

Distribution

• npm — npm install -g @memlink/cli
• Standalone binaries — install.sh (Unix) / install.ps1 (Windows) from GitHub Releases
• Docker — coming soon

License

Apache License 2.0. See LICENSE for details.