# Memrec

> Local-first AI memory with project isolation — for terminal, for private use

- **Type:** MCP server
- **Install:** `agentstack add mcp-itcraft-cn-memrec`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [itcraft-cn](https://agentstack.voostack.com/s/itcraft-cn)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [itcraft-cn](https://github.com/itcraft-cn)
- **Source:** https://github.com/itcraft-cn/memrec
- **Website:** https://itcraft.cn/memrec

## Install

```sh
agentstack add mcp-itcraft-cn-memrec
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

[中文版](README_cn.md) | English

# MemRec — AI Memory Persistence System

> Local-first AI memory with project isolation — for terminal, for private use

Local memory persistence system for AI CLI tools, providing cross-session memory recovery, knowledge accumulation, and conversation archival.

## Features

- **Project Isolation** — Auto-detect git root, .mr_pid persistence, independent memory per project
- **Semantic Search** — Local ONNX model (384-dim), zero API cost, all data stays local
- **Cross-Project Search** — `--all` flag to discover related knowledge across projects
- **AI-first Design** — JSON output by default, concise commands, Skill integration
- **High Performance** — Rust, 7.5KB) automatically split into chunks
- **Systemd Integration** — Manage daemon with `systemctl --user`

## Quick Start

### Install

```bash
# One command to install everything
cargo install --locked mr-install
mr-install
```

`mr-install` automatically:
1. Installs memrec/memrecd via `cargo install`
2. Creates `~/.memrec/` directory structure
3. Downloads ONNX embedding model (~90MB)
4. Registers and starts the daemon service
5. Verifies the installation

| Platform | Binary Path | Data Path |
|----------|------------|-----------|
| Linux | `~/.local/bin/` | `~/.memrec/` |
| macOS | `~/bin/` | `~/.memrec/` |

Mirror options for model download:

```bash
mr-install --use-hf-mirror           # Use hf-mirror.com (China)
mr-install --mirror-base-url    # Custom mirror
```

### Usage

```bash
# Add memories
memrec add "Choose JWT auth" --mtype decision --tag critical
memrec add "RAII: resource acquisition is initialization" --mtype knowledge --tag best-practice --tag rust
memrec add "User prefers verbose output" --mtype preference --tag output --global

# Semantic search
memrec search "auth"                        # Current project + global
memrec search "performance" --project-only  # Current project only
memrec search "preferences" --global-only   # Global memories only
memrec search "xlsb" --all                  # Across all projects

# Other commands
memrec list --limit 20
memrec get 
memrec stats
memrec version
```

## Project Isolation

MemRec automatically creates independent memory spaces for different projects:

```
project-a/           project-b/
├── .mr_pid          ├── .mr_pid        ← Auto-created, different IDs
├── .gitignore       ├── .gitignore     ← Add .mr_pid to .gitignore
└── src/             └── src/
```

- **Git repos**: Auto-detect git root
- **Non-git dirs**: Use current working directory
- **Global memories**: `--global` flag, accessible from all projects
- **Cross-project search**: `--all` searches across all projects

## Memory Types

| Type | Flag | Purpose |
|------|------|---------|
| Decision | `decision` | Key technical/business decisions |
| Knowledge | `knowledge` | Knowledge (subdivide via tags: `fact`/`best-practice`/`algorithm`/`tool`) |
| Context | `context` | Project config, environment info |
| Preference | `preference` | User preferences (recommend `--global`) |
| Conversation | `conversation` | Conversation records (default) |

## Data Location

```
~/.memrec/
├── config.toml           # Configuration
├── memrecd.sock          # Unix Socket
├── data/                 # RocksDB memory metadata
├── vectors/              # RocksDB vector storage
└── models/               # ONNX Embedding model
```

## Environment Variables

| Variable | Purpose | Default |
|----------|---------|---------|
| `MEMREC_MODEL_DIR` | Custom model path | `~/.memrec/models/Qdrant--all-MiniLM-L6-v2-onnx/` |
| `MEMREC_MIN_SCORE` | Min similarity score | `0.75` |
| `RUST_LOG` | Log level | `info` |

## Documentation

- [Installation Guide](docs/installation.md)
- [User Guide](docs/user-guide.md)
- [Skill Documentation](docs/skills/memrec-skill.md)

## Project Structure

```
memrec/
├── common/       # Shared types and protocol
├── memrecd/      # Daemon service
├── memrec/       # CLI tool
├── mr-install/   # Installer
└── docs/         # Documentation
```

## License

Apache-2.0

## Changelog

See [CHANGELOG.md](CHANGELOG.md)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [itcraft-cn](https://github.com/itcraft-cn)
- **Source:** [itcraft-cn/memrec](https://github.com/itcraft-cn/memrec)
- **License:** Apache-2.0
- **Homepage:** https://itcraft.cn/memrec

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-itcraft-cn-memrec
- Seller: https://agentstack.voostack.com/s/itcraft-cn
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.