Velixar MCP Server

npm License

The first cognitive memory server for AI assistants. Not a vector database wrapper — a full reasoning layer that gives your AI persistent memory, a knowledge graph, identity awareness, contradiction detection, and belief tracking across every session.

Works with any Model Context Protocol client: Claude Desktop, Kiro, Cursor, Windsurf, Continue.dev, or custom hosts.

Why This Exists

Every AI assistant starts from zero every conversation. Velixar fixes that — but not by just storing and retrieving text. The MCP server gives your assistant the ability to:

Orient itself in a workspace with a single call — no manual context assembly
Track how beliefs evolve over time and surface when they contradict
Build and traverse a knowledge graph of entities and relationships it discovers
Maintain a persistent identity model of who you are, what you prefer, and how you work
Distill sessions into durable memories automatically, with deduplication
Import and export your entire memory corpus for backup or migration

40 tools. 5 live resources. 19 workflow prompts. One npm install.

Quick Start

npm install -g velixar-mcp-server

Get an API key at velixarai.com/settings/api-keys, then add to your MCP client:

{
  "mcpServers": {
    "velixar": {
      "command": "velixar-mcp-server",
      "env": {
        "VELIXAR_API_KEY": "vlx_your_key_here"
      }
    }
  }
}

Restart your assistant. Done.

Tool Surface

Memory

Tool	What it does
`velixar_store`	Store a memory with tags, tier, and type
`velixar_search`	Semantic search across all memories
`velixar_list`	Browse with pagination and filtering
`velixar_update`	Edit content or tags on an existing memory
`velixar_delete`	Remove a memory

Cognitive

Tool	What it does
`velixar_context`	Synthesized workspace briefing — orientation in one call
`velixar_identity`	Get, store, or update the user's profile, preferences, and expertise
`velixar_contradictions`	Surface conflicting facts or beliefs with resolution guidance
`velixar_timeline`	How a topic or belief evolved over time
`velixar_patterns`	Recurring problem/solution motifs across your history
`velixar_inspect`	Deep inspection of a specific memory with full provenance chain
`velixar_graph_traverse`	Walk entity relationships — "what connects to X?"
`velixar_distill`	Extract durable memories from session content with deduplication

Lifecycle

Tool	What it does
`velixar_session_save`	Save a session summary for later recall
`velixar_session_recall`	Restore context from a previous session
`velixar_batch_store`	Store up to 20 memories in one call
`velixar_batch_search`	Run up to 10 search queries simultaneously
`velixar_consolidate`	Merge related memories into a single durable memory
`velixar_retag`	Bulk update tags across memories
`velixar_export`	Export memories as JSON or Markdown, optionally with graph data
`velixar_import`	Bulk import from JSON, Markdown, Notion, or Obsidian exports

System

Tool	What it does
`velixar_health`	Backend connectivity, latency, workspace status
`velixar_debug`	Cache state, circuit breaker, API timings
`velixar_capabilities`	Feature list, tool inventory, resource URIs
`velixar_security`	Get or set content scanning mode

Live Resources

Resources are injected into your assistant's context automatically — no tool call needed.

Resource	What it provides
`velixar://system/constitution`	Behavioral rules and cognitive modes for the assistant
`velixar://identity/current`	Your persistent user profile
`velixar://memories/recent`	Most recent memories (compact)
`velixar://memories/relevant`	Contextually relevant memories based on current activity
`velixar://domains/{domain}/shadow_graph`	Knowledge graph view for a specific domain

Workflow Prompts

16 built-in prompts that guide multi-step reasoning workflows:

Orientation — recall prior reasoning, build project context, profile an entity, orient-then-narrow
Conflict — resolve contradictions, identify knowledge gaps
Continuity — trace belief evolution, resume sessions, reconstruct decision paths
Lifecycle — distill sessions, consolidate topic memory, retag recent memories
Identity — summarize user identity, detect preference shifts, align response style
Enterprise — evaluate enterprise fit for a domain

Workspace Isolation

Memories are scoped to workspaces. Your personal project never bleeds into work.

Priority	Source	How
1	`VELIXAR_WORKSPACE_ID` env var	Explicit
2	`.velixar.json` in project root	`{ "workspace_id": "my-project" }`
3	Git root directory name	Automatic

Host Compatibility

Host	Tools	Resources	Prompts
Kiro CLI	✅	✅	✅
Claude Desktop	✅	✅	✅
Cursor	✅	⚠️	—
Windsurf	✅	⚠️	—
Continue.dev	✅	✅	✅

When a host doesn't support resources or prompts, the server degrades gracefully — all tools still work independently.

Environment Variables

Variable	Required	Description
`VELIXAR_API_KEY`	Yes	Your API key (starts with `vlx_`)
`VELIXAR_WORKSPACE_ID`	No	Explicit workspace scope
`VELIXAR_API_URL`	No	Custom API endpoint
`VELIXAR_USER_ID`	No	Explicit end-user identity. Leave unset (recommended): the API derives scope from your key — you see your own memories, same as the dashboard. Set it only when one key serves multiple named end users
`VELIXAR_DEBUG`	No	`true` for verbose logging
`VELIXAR_LOG_FORMAT`	No	`json` for structured Datadog/CloudWatch logging
`VELIXAR_HEALTH_PORT`	No	Port for HTTP health check endpoint

Reliability

Automatic retry with exponential backoff (3 attempts)
Circuit breaker — opens after sustained failures, auto-recovers
Cache fallback — serves stale data during outages rather than failing
Structured logging compatible with Datadog and CloudWatch

SDKs

Use Velixar directly from code:

JavaScript/TypeScript: npm install velixar — docs
Python: pip install velixar — docs

CI/CD Integration

GitHub Actions: velixar-memory-sync — distill PR merges into memories
GitHub Actions: velixar-decision-capture — store issue resolutions as decisions
Webhook: POST /webhook/ci — generic CI event ingestion

License

MIT