Rusty Memory MCP

Rusty Memory MCP is a no‑fuss memory server for coding agents. It chunks text, generates embeddings, and stores vectors in Qdrant. You can run it as:

An MCP server over stdio for editors/agents
A local HTTP service for simple scripts

If you want to hack on the codebase or learn how it works internally, jump to Developer Docs below.

Quick Start (MCP in your editor)

Install the binaries
```
cargo install rustymcp
```
This installs:
- rusty_mem_mcp (MCP server)
- rustymcp (HTTP server)
- metrics-post (helper used by scripts)

Start Qdrant (vector database)

docker run --pull=always -p 6333:6333 qdrant/qdrant:latest

Configure environment

Copy .env.example to .env and edit values, or provide the same variables via your MCP client config:

Required variables:
- QDRANT_URL (e.g. http://127.0.0.1:6333)
- QDRANT_COLLECTION_NAME (e.g. rusty-mem)
- EMBEDDING_PROVIDER (ollama enables the local client; other values use the deterministic fallback for now)
- EMBEDDING_MODEL (free‑form, e.g. nomic-embed-text)
- EMBEDDING_DIMENSION (must match your model, e.g. 768)
- OLLAMA_URL (optional, defaults to http://127.0.0.1:11434 when EMBEDDING_PROVIDER=ollama)
Launch the MCP server
```
rusty_mem_mcp
```

Add to your agent

Codex CLI (~/.codex/config.toml):

[mcp_servers.rusty_mem]
command = "rusty_mem_mcp" # or use the full path to the binary
args = []
transport = "stdio"

  [mcp_servers.rusty_mem.env]
  QDRANT_URL = "http://127.0.0.1:6333"
  QDRANT_COLLECTION_NAME = "rusty-mem"
  EMBEDDING_PROVIDER = "ollama"
  EMBEDDING_MODEL = "nomic-embed-text"
  EMBEDDING_DIMENSION = "768"
  OLLAMA_URL = "http://127.0.0.1:11434" # omit to use the default

JSON clients (Kilo, Cline, Roo Code):

{
  "mcpServers": {
    "rusty": {
      "command": "rusty_mem_mcp",
      "args": [],
      "transport": "stdio",
      "env": {
        "QDRANT_URL": "http://127.0.0.1:6333",
        "QDRANT_COLLECTION_NAME": "rusty-mem",
      "EMBEDDING_PROVIDER": "ollama",
      "EMBEDDING_MODEL": "nomic-embed-text",
       "EMBEDDING_DIMENSION": "768",
       "OLLAMA_URL": "http://127.0.0.1:11434"
      }
    }
  }
}

Try it

From your agent, use:
- get-collections → list Qdrant collections
- listResources → discover read-only resources; use readResource on mcp://rusty-mem/memory-types and mcp://rusty-mem/health for metadata/health snapshots
- new-collection → create or resize a collection
- push (alias: index) → index text with optional metadata (project_id, memory_type, tags, source_uri)
- metrics → view counters (documentsIndexed, chunksIndexed, lastChunkSize)

Optional: Run the HTTP server

If you prefer HTTP, set the same environment and run:

rustymcp

By default the server binds the first free port in 4100–4199 (or SERVER_PORT if set). Example:

curl -sS -X POST http://127.0.0.1:4100/index \
  -H 'Content-Type: application/json' \
  -d '{"text":"hello from http"}'

Returns { "chunks_indexed": <number>, "chunk_size": <number>, "inserted": <number>, "updated": <number>, "skipped_duplicates": <number> } on success.

Having trouble? See docs/Troubleshooting.md.

Developer Docs

If you want to extend Rusty Memory or understand the architecture:

Configuration reference and client snippets: docs/Configuration.md
Architecture and module overview: docs/Design.md
Editor integration examples: docs/Editors.md
Development guide (style, tests, scripts): docs/Development.md

License

Licensed under the PolyForm Noncommercial License 1.0.0. Free for non‑commercial use.

Support