Agent Integration (MCP)

VecminDB plugs into Cursor, Claude Code, and any MCP-compatible agent tool with zero code: configure the connection once, install the memory rules with a single sentence, and your agent automatically distills valuable conversation turns into long-term memory — and searches that memory before every answer.

1. Add the MCP connection (the only manual step)

Every tool takes the same two parameters: http://<host>:5520/api/v1/mcp/sse plus the x-api-key header. Only the location differs:

Cursor — create .cursor/mcp.json in the project (or ~/.cursor/mcp.json for all projects), then restart Cursor:

{
  "mcpServers": {
    "vecmindb": {
      "url": "http://localhost:5520/api/v1/mcp/sse",
      "headers": { "x-api-key": "<your Admin API Key>" }
    }
  }
}

Claude Code — create .mcp.json in the project root:

{
  "mcpServers": {
    "vecmindb": {
      "url": "http://localhost:5520/api/v1/mcp/sse",
      "headers": { "x-api-key": "<your Admin API Key>" }
    }
  }
}

…or add it from the CLI:

claude mcp add vecmindb --transport sse \
  --url http://localhost:5520/api/v1/mcp/sse \
  --header "x-api-key: <your Admin API Key>"

The Admin API Key is generated on first start and printed to the container logs (docker logs vecmindb | grep "Your Admin API Key"), or pinned via the VECMIN__SECURITY__ADMIN_KEY environment variable. For remote deployments, enable TLS (see the Installation & Ops guide).

2. Install the memory rules with one sentence

Once connected, tell your agent:

Install vecmindb memory rules

The agent calls the built-in get_memory_rules tool; the server returns the corrected rule block plus the exact file to write (Claude Code → CLAUDE.md; Cursor → .cursor/rules/vecmindb-memory.mdc). The agent shows you the block first and writes it only after your confirmation — just the marked section is replaced, nothing else in the file is touched, and re-running never duplicates the block. Then start a new session. Rules are server-generated, upgrade with the product, and ship in both English and Chinese (lang=en / lang=zh).

Try it now: 60 seconds to your first "it remembered!"

① Store something — tell your agent: "Remember: customer Acme requires on-prem deployment and data must never leave our intranet." → it calls store_memory (long-term constraints automatically get the is_factual strong anchor).

② Prove it survived — open a new session and ask: "What are Acme's deployment requirements?" → it calls search_memory and answers with the fact you stored, even though this session knew nothing about it.

③ Watch it live — observe every memory read & write on the server in real time:

docker logs -f vecmindb 2>&1 | grep "tools/call"

3. What your agent does once the rules are active

• Search before every answer: calls search_memory (top_k 3–5) for relevant memories — all topics qualify (project constraints, client preferences, recipes). A server-side relevance floor (memory.search_min_score, default 0.70) returns "no relevant memory" for unrelated topics, so the agent answers directly.
• Store after informative turns: calls store_memory with a distilled summary as the text, key excerpts/data/commitments attached in metadata.detail; long-term constraints, client requirements, and architecture decisions are flagged is_factual:true (strong anchor, exempt from forgetting). Pure greetings are skipped.
• Projection guard: when answering questions unrelated to VecminDB, the agent does not import VecminDB project context — memories are used by topic.
• Honesty clause: failed reads or writes are reported honestly, never faked.

4. Available tools

10 core tools are visible after integration: store_memory, search_memory, list_memories, get_memory, forget, update_memory, memory_status, consolidate, register_factuality_template / remove_factuality_template, and get_memory_rules. Multimodal tools (store_media / get_media / search_media_by_image) are disabled by default and require media.clip_collection in the configuration.

5. Verify automatic reads & writes

The server logs every MCP tool call. Watch it live after deployment:

docker logs -f vecmindb 2>&1 | grep "tools/call"

6. Teams & multi-tenant — one memory per team

Every API key maps to one tenant and one memory collection (mem_<tenant>). Team members sharing a key work in the same memory space; different tenants are isolated by default. One tenant per team gives the team a shared brain; one tenant per project gives hard isolation.

① Create a tenant (admin, one command; the engine provisions the collection, issues the key and persists it into config.yml — restarts survive; the key is returned once):

curl -X POST http://<host>:5520/api/v1/tenants \
  -H "x-api-key: <ADMIN_KEY>" -H "Content-Type: application/json" \
  -d '{"name": "acme-team"}'

# → {"tenant":"acme-team","collection":"mem_acme-team","key":"<uuid>"}

② Distribute the key — each member pastes it as the x-api-key in their MCP config (see section 1) and connects to the same shared memory.

③ Cross-team sharing (optional) — a tenant owner can grant another existing tenant read-only access to their own collection with the set_tenant_grant tool (or declare tenant_grants: in config.yml). Two hard guarantees: writes always stay in the caller's own tenant collection, and you can only ever grant a collection you own.