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)

1. Install the binaries

   cargo install rustymcp
   

   This installs:

   • rusty_mem_mcp (MCP server)
   • rustymcp (HTTP server)
   • metrics-post (helper used by scripts)

2. Start Qdrant (vector database)

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

3. 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)

4. Launch the MCP server

   rusty_mem_mcp
   

5. 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"
           }
         }
       }
     }
     

6. Try it

   From your agent, use:

   • push → ingest text with optional metadata (project_id, memory_type, tags, source_uri)
   • search → retrieve memories semantically with filters for project, memory type, tags, time range, and score threshold
   • summarize → condense episodic memories into semantic summaries with provenance and idempotent summary_keys
   • get-collections → list Qdrant collections
   • new-collection → create or resize a collection
   • metrics → view counters (documentsIndexed, chunksIndexed, lastChunkSize)
   • listResources → discover read-only resources; use readResource on:
     • mcp://memory-types
     • mcp://projects
     • mcp://health
     • mcp://settings (search defaults)
     • mcp://usage (usage policy and recommended flows)
     • Template: mcp://{project_id}/tags

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

Issues and PRs are welcome. If anything in the Quick Start is unclear, please open an issue so we can make onboarding even smoother.