Content
<p align="center">
<img src="https://raw.githubusercontent.com/rblez/memlink/main/public/memlink.png" alt="Memlink Logo" width="200" />
</p>
<h1 align="center">Memlink</h1>
<p align="center">
<strong>Universal Memory for AI Agents</strong><br/>
Self-hosted · HTTP streamable · No cloud
</p>
<p align="center">
<a href="https://github.com/rblez/memlink/releases/latest"><img src="https://img.shields.io/github/v/release/rblez/memlink?style=flat-square" alt="Release"/></a>
<a href="https://github.com/rblez/memlink/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache_2.0-blue?style=flat-square" alt="License"/></a>
<a href="https://www.npmjs.com/package/@memlink/cli"><img src="https://img.shields.io/npm/v/@memlink/cli?style=flat-square" alt="npm"/></a>
</p>
---
Memlink is a self-hosted [MCP](https://modelcontextprotocol.io) server that gives AI agents persistent, organized memory. One install, one URL, any agent connects — Devin Desktop, Cursor, Windsurf, Claude Code, or any MCP-compatible HTTP client.
## Installation
```bash
npm install -g @memlink/cli
```
Requires Node.js 18+ or Bun 1.0+.
**From source:**
```bash
git clone https://github.com/rblez/memlink.git
cd memlink && bun install && npm run build
```
## Quick Start
```bash
memlink serve --daemon # Start server in background
memlink serve --status # Verify it's running
```
Configure your agent with `http://localhost:4444/mcp` (see below).
## Connecting an Agent
Add this JSON to your agent's MCP configuration:
```json
{
"mcpServers": {
"memlink": {
"type": "http",
"url": "http://localhost:4444/mcp"
}
}
}
```
**Devin Desktop** → Settings → MCP Servers
**Cursor** → Settings → MCP
**Windsurf** → `~/.codeium/windsurf/mcp_config.json`
**Claude Code** → `MCP_SERVERS_CONFIG` env var or `.mcp.json`
**Codex CLI** → `~/.codexclirc` or project `.codexclirc`
After connecting, agents discover the `memory_read`, `memory_edit`, `memory_search`, and `memory_sync` tools automatically. Start every new session by calling `memory_read` to load stored context.
## Commands
| Command | Description |
|---------|-------------|
| `memlink` | Show server URL, memory stats, and daemon status |
| `memlink serve` | Start the MCP server |
| `memlink serve --daemon` | Run in background |
| `memlink serve --stop` | Stop the daemon |
| `memlink serve --status` | Show server status + stats |
No CRUD commands — all memory operations happen through the MCP tools.
## MCP Tools
| Tool | Description |
|------|-------------|
| `memory_read` | Read index or a specific entry (`id?`, `title?`, `full?`) |
| `memory_edit` | Create or update an entry (`title`, `content`, `tags?`) |
| `memory_search` | Search entries by query |
| `memory_sync` | Memory stats (count, size, last updated) |
## Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `MEMLINK_DIR` | `~/.memlink` | Data directory |
| `MEMLINK_PORT` / `PORT` | `4444` | Server port |
| `MEMLINK_HOST` / `HOST` | `localhost` | Server host |
| `MEMLINK_NO_COLOR` | — | Disable colored output |
## Data Layout
```
~/.memlink/
├── settings.json # Global config
├── .serve.pid # Daemon PID
└── default/ # Memory (auto-created)
├── meta.json # Memory metadata
├── index.json # Entry index (titles, tags, timestamps)
├── 1.md, 2.md, ... # Entries with YAML frontmatter
└── .backups/ # Timestamped backups on every write
```
## Robustness
- **Atomic writes** — `.tmp` + `renameSync()`, no partial writes
- **Auto-backups** — every mutation backed up to `.backups/`
- **File lock** — concurrent writes serialized via `.lock` with TTL + retry
- **Health ticker** — 30s heartbeat written to `.health`
- **Rate limiting** — 1000 req/min per IP
## Development
```bash
bun install # Install dependencies
npm run build # Build CLI + server
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 # Colors, badges, branding
├── cli/daemon.ts # Detached spawn (Windows VBScript)
├── server/index.ts # MCP server (Express + MCP SDK)
└── core/
├── storage.ts # Entry CRUD, atomic writes, backups
├── meta.ts # Per-memory meta.json
├── routing.ts # Default memory route
├── health.ts # Daemon heartbeat
├── lock.ts # File lock with TTL
├── memory.ts # Config + CLI helpers
└── types.ts # Types, constants, MEMLINK_VERSION
tests/ # memory, server, unit, vbscript
```
## License
Apache License 2.0 — see [LICENSE](LICENSE).
