velixar-mcp-server 0.2.4 → 1.2.0

package/README.md

@@ -3,24 +3,31 @@
 [![npm](https://img.shields.io/npm/v/velixar-mcp-server)](https://www.npmjs.com/package/velixar-mcp-server)
 [![License](https://img.shields.io/github/license/VelixarAi/velixar-mcp-server)](LICENSE)
 
-MCP server that gives any AI assistant persistent memory via [Velixar](https://velixarai.com). Works with any [Model Context Protocol](https://modelcontextprotocol.io)-compatible client — Claude Desktop, Kiro, Cursor, Windsurf, Continue, or any MCP-enabled tool.
+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.
 
-## What It Does
+Works with any [Model Context Protocol](https://modelcontextprotocol.io) client: Claude Desktop, Kiro, Cursor, Windsurf, Continue.dev, or custom hosts.
 
-Your AI assistant forgets everything between sessions. This server fixes that. It connects to Velixar's memory API and exposes 5 tools that let your assistant store, search, list, update, and delete memories that persist across conversations.
+## Why This Exists
 
-## Setup
+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:
 
-1. Get an API key at [velixarai.com/settings/api-keys](https://velixarai.com/settings/api-keys)
+- **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
 
-2. Install:
 ```bash
 npm install -g velixar-mcp-server
 ```
 
-3. Add to your MCP client config:
+Get an API key at [velixarai.com/settings/api-keys](https://velixarai.com/settings/api-keys), then add to your MCP client:
 
-**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
 ```json
 {
   "mcpServers": {
@@ -34,82 +41,131 @@ npm install -g velixar-mcp-server
 }
 ```
 
-**Kiro CLI** (`~/.kiro/settings/mcp.json`):
-```json
-{
-  "mcpServers": {
-    "velixar": {
-      "command": "velixar-mcp-server",
-      "env": {
-        "VELIXAR_API_KEY": "vlx_your_key_here"
-      }
-    }
-  }
-}
-```
+Restart your assistant. Done.
 
-**Cursor** (`.cursor/mcp.json` in your project):
-```json
-{
-  "mcpServers": {
-    "velixar": {
-      "command": "velixar-mcp-server",
-      "env": {
-        "VELIXAR_API_KEY": "vlx_your_key_here"
-      }
-    }
-  }
-}
-```
+## Tool Surface
 
-4. Restart your AI assistant
+### Memory
 
-## Tools
+| 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 |
 
-| Tool | Description |
+### 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_store` | Store a memory with optional tags and tier |
-| `velixar_search` | Semantic search across memories |
-| `velixar_list` | Browse memories with pagination |
-| `velixar_update` | Edit an existing memory |
-| `velixar_delete` | Delete a memory by ID |
+| `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.
 
-## Memory Tiers
+| 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 |
 
-| Tier | Name | Use Case |
-|------|------|----------|
-| 0 | Pinned | Critical facts, never expire |
-| 1 | Session | Current conversation context |
-| 2 | Semantic | Long-term memories (default) |
-| 3 | Organization | Shared team knowledge |
+## 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 Velixar API key |
+| `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 | User ID for memory scoping (default: `kiro-cli`) |
+| `VELIXAR_USER_ID` | No | User ID for memory scoping |
+| `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 |
 
-## Example
+## Reliability
 
-Once configured, your AI assistant can:
+- 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
 
-```
-You: Remember that our production database is on us-east-1 and staging is us-west-2
-Assistant: ✓ Stored memory
+## SDKs
 
-You: Which region is our staging database in?
-Assistant: Based on my memory, your staging database is in us-west-2.
-```
+Use Velixar directly from code:
 
-Memories persist across sessions, restarts, and even different machines — as long as they use the same API key.
+- **JavaScript/TypeScript**: `npm install velixar` — [docs](https://docs.velixarai.com/sdks/javascript)
+- **Python**: `pip install velixar` — [docs](https://docs.velixarai.com/sdks/python)
 
-## Related
+## CI/CD Integration
 
-- [velixar (JavaScript SDK)](https://github.com/VelixarAi/velixar-js) — Use Velixar directly in Node.js/TypeScript
-- [velixar (Python SDK)](https://github.com/VelixarAi/velixar-python) — Python client with LangChain/LlamaIndex integrations
-- [velixarai.com](https://velixarai.com) — Dashboard, API keys, and docs
+- **GitHub Actions**: [velixar-memory-sync](github-actions/velixar-memory-sync) — distill PR merges into memories
+- **GitHub Actions**: [velixar-decision-capture](github-actions/velixar-decision-capture) — store issue resolutions as decisions
+- **Webhook**: `POST /webhook/ci` — generic CI event ingestion
 
 ## License
 

package/dist/api.d.ts

@@ -0,0 +1,64 @@
+import type { ApiConfig, ApiTiming, MemoryItem, ResponseMeta, VelixarError, VelixarResponse } from './types.js';
+import type { ValidatedRawMemory } from './validate.js';
+export declare function setClientRoots(roots: Array<{
+    uri: string;
+    name?: string;
+}>): void;
+export declare function validateWorkspace(config: ApiConfig): string | null;
+export declare function loadConfig(): ApiConfig;
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export declare function log(level: LogLevel, msg: string, fields?: Record<string, unknown>): void;
+export declare function getRateLimitInfo(): {
+    remaining: number;
+    total: number;
+};
+export declare function getTimings(): ApiTiming[];
+export declare function getRetryStats(): {
+    retryCount: number;
+    fallbackCount: number;
+};
+export declare function getCircuitState(): {
+    failures: number;
+    open: boolean;
+    threshold: number;
+    reset_ms: number;
+    consecutive_opens: number;
+};
+export declare class ApiClient {
+    private config;
+    constructor(config: ApiConfig);
+    request<T>(path: string, options?: RequestInit & {
+        cacheable?: boolean;
+    }): Promise<T>;
+    get<T>(path: string, cacheable?: boolean): Promise<T>;
+    post<T>(path: string, body: unknown): Promise<T>;
+    patch<T>(path: string, body: unknown): Promise<T>;
+    delete<T>(path: string): Promise<T>;
+    requestValidated<T>(path: string, options: RequestInit & {
+        cacheable?: boolean;
+    }, validate: (raw: unknown, endpoint: string) => T): Promise<T>;
+    getValidated<T>(path: string, validate: (raw: unknown, endpoint: string) => T, cacheable?: boolean): Promise<T>;
+    postValidated<T>(path: string, body: unknown, validate: (raw: unknown, endpoint: string) => T): Promise<T>;
+    patchValidated<T>(path: string, body: unknown, validate: (raw: unknown, endpoint: string) => T): Promise<T>;
+}
+/** Raw memory shape from backend — use ValidatedRawMemory from validate.ts for new code */
+interface RawMemory {
+    id: string;
+    content: string;
+    score?: number;
+    tier?: number;
+    type?: string | null;
+    tags?: string[];
+    salience?: number;
+    created_at?: string;
+    updated_at?: string;
+    previous_memory_id?: string | null;
+    timestamp?: string;
+}
+export declare function normalizeMemory(raw: RawMemory | ValidatedRawMemory): MemoryItem;
+export declare function makeMeta(config: ApiConfig, overrides?: Partial<ResponseMeta>): ResponseMeta;
+export declare function wrapResponse<T>(data: T, config: ApiConfig, overrides?: Partial<ResponseMeta>): VelixarResponse<T>;
+export declare function makeError(code: string, message: string, retryable?: boolean): VelixarError;
+export declare function isApiError(e: unknown): e is Error;
+export {};
+//# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}