Related Pages

Related topics: System Architecture, Quick Start Guide, MCP Server Integration

Introduction to Via

What is Via?

Via is the universal integration layer for AI development tools, created by Vektor Memory. It functions as a CLI (Command Line Interface) that connects Claude, Cursor, Windsurf, and ChatGPT to a shared memory system, task board, and context bus—enabling your work to persist across every tool, every session, and every machine.

The name "Via" comes from Latin, meaning "path, road, or through," which reflects its role as the bus that routes context and execution between AI tools. Source: [SPEC.md] via.mjs entry point handles all CLI commands including via init, via memory, via task, via log, via ask, and via diff. Source: [README.md] The MCP server exposes all 12 commands as MCP tools, allowing Claude Code, Cursor, and any MCP-compatible client to access Via's functionality directly. Source: [SPEC.md] The via serve command runs Via as an MCP server over stdio and HTTP+SSE. Source: [CHANGELOG.md] The via init command wires Via into every detected AI tool with one command, fully configured. Source: [README.md] The project uses Node.js >= 18 with native fetch and minimal dependencies, installable via npx via for zero-install usage. Source: [SPEC.md] The license is Apache 2.0, and the project is authored by Vektor Memory with bug reports directed to [email protected]. Source: [package.json] The project stores all local data in ~/.via/, including config.json, tasks.db, audit.db, personas/, spend/, and handoffs/ directories. Source: [SPEC.md] The project includes connectors for Claude Code, Cursor, Windsurf, ChatGPT, and LangChain, plus a Slipstream upgrade bridge. Source: [SPEC.md]

The Problem Via Solves

Every AI tool remembers inside its own walls. Claude forgets what you did in Cursor. Cursor forgets what you built in Windsurf. The moment you switch tools—or open a new session—context resets to zero. This fragmentation creates significant challenges for developers who work across multiple AI-powered tools.

Via solves this by providing a unified bus that:

• Persists context across all connected AI tools
• Shares task boards that any tool can read and write via MCP
• Maintains audit trails of decisions across sessions
• Enables session handoff between tools
• Provides cross-tool memory search and retrieval

The architecture ensures Via uses SQLite locally with no embeddings and no API calls for indexing. Semantic search, graph traversal, and team-shared context are available through an optional upgrade to Vektor Slipstream. Source: [README.md] The data storage policy guarantees that VEKTOR Memory does not store any user data on their servers—memories, credentials, and vault files live on the user's machine only. Source: [SECURITY.md]

Architecture Overview

High-Level System Design

graph TD
    subgraph "AI Tools"
        Claude[Claude Code]
        Cursor[Cursor]
        Windsurf[Windsurf]
        ChatGPT[ChatGPT]
    end
    
    subgraph "Via Core"
        CLI[CLI Interface<br/>via.mjs]
        Commands[Commands Module<br/>commands/*.mjs]
        Utils[Utils Module<br/>utils/*.mjs]
        DB[(SQLite<br/>Local Storage)]
    end
    
    subgraph "Connectors"
        ClaudeConn[claude.mjs]
        CursorConn[cursor.mjs]
        WindsurfConn[windsurf.mjs]
        ChatGPTConn[chatgpt.mjs]
        LangChain[langchain.mjs]
        Slipstream[slipstream.mjs]
    end
    
    subgraph "Data Stores"
        Config[~/.via/config.json]
        Tasks[tasks.db]
        Audit[audit.db]
        Personas[personas/]
        Spend[spend/]
    end
    
    Claude --> CLI
    Cursor --> CLI
    Windsurf --> CLI
    ChatGPT --> CLI
    
    CLI --> Commands
    CLI --> Utils
    Commands --> DB
    Utils --> Config
    
    DB --> Tasks
    DB --> Audit
    Config --> Personas
    Config --> Spend
    
    Commands --> ClaudeConn
    Commands --> CursorConn
    Commands --> WindsurfConn
    Commands --> Slipstream

Repository Structure

The Via repository follows a clean modular structure with dedicated directories for connectors, commands, and utilities. Source: [SPEC.md]

CLI Entry Point

The single .mjs entry point handles all command routing, consistent with Vex and Vek-Sync conventions. Source: [SPEC.md] Via follows the same patterns as other Vektor products:

• Single .mjs entry point (via.mjs)
• connectors/ for tool adapters
• utils/ for shared internals
• Progress bars and summary blocks for long operations
• --json flag on all commands for machine-readable output

Key Features and Commands

Command Overview

Via provides 12 primary commands that can be accessed via CLI or MCP. Source: [CHANGELOG.md] The via ingest command handles URL, file, folder, and inline text ingestion. Source: [CHANGELOG.md] The via context command provides multi-tool context formatting for Claude, Cursor, Windsurf, and ChatGPT. Source: [CHANGELOG.md] The via task command manages a shared task board backed by SQLite. Source: [CHANGELOG.md] The via audit command maintains an AI decision compliance log with export capability. Source: [CHANGELOG.md] The via scaffold command provides one-command project setup for all connected tools. Source: [CHANGELOG.md] The via watch command handles desktop and webhook event routing. Source: [CHANGELOG.md] The via handoff command enables cross-tool working state export and import. Source: [CHANGELOG.md] The via status command displays an ecosystem health dashboard. Source: [CHANGELOG.md] The via persona command manages named AI personas. Source: [CHANGELOG.md] The via spend command tracks AI costs. Source: [CHANGELOG.md] The via sync command synchronizes state across multiple machines. Source: [CHANGELOG.md] The via upgrade command provides a Slipstream upgrade bridge. Source: [CHANGELOG.md]

Memory and Context Management

The via memory command provides fact storage and relationship-aware codebase indexing. Source: [README.md]

via memory add "JWT tokens expire in 1h"          # store a fact
via memory add --file ./src/                      # index a codebase
via memory search "auth"                          # search + related files
via memory graph                                  # show import relationships
via memory list                                   # list indexed files + facts

The memory system extracts symbols and import edges from JavaScript, TypeScript, Python, Go, and Rust. Search traverses relationships, not just text—returning auth.js plus every file that imports it when searching for "auth". Source: [README.md]

Via uses SQLite locally with no embeddings and no API calls for indexing. This provides keyword search only, with an optional upgrade to Slipstream for BM25 and semantic dual-channel recall plus graph traversal. Source: [SPEC.md]

Task Management

The via task command provides a shared persistent task board that any AI tool can read and write via MCP. Source: [CHANGELOG.md] Tasks are stored in a SQLite database with fields for id, title, status (open, in-progress, done, blocked), tool, persona, created_at, updated_at, and notes. Source: [SPEC.md]

via task add "refactor auth module" --high
via task
via task done <id>
via task start <id>

The local implementation provides a flat task list, while Slipstream offers tasks linked to the memory graph and causally connected to decisions. Source: [SPEC.md]

Session Handoff

The via handoff command exports or imports a .vstate.json session state file. Source: [SPEC.md]

via handoff --export                        # saves .vstate.json
via handoff --import ./sprint3.vstate.json  # restore on any machine
via handoff --list

The handoff file captures the current task description, open questions, decisions made, working file paths, and tool-specific context that can be transferred between tools. Source: [SPEC.md]

Logging and Diff

The via log command provides unified activity logging with auto-capture for Claude Code sessions. Source: [README.md]

via log "decided to use postgres" --tool claude
via log --scan     # one-shot capture of all Claude Code sessions
via log --watch    # live capture as sessions complete
via log --today
via log search "postgres"

The via diff command compares what two AI tools said about the same prompt, showing where they agree, diverge, and what unique concepts each brought. Source: [README.md]

via diff "explain microservices"
via diff add claude "Microservices split apps into small independent services..."
via diff add cursor "Microservices are small focused services that communicate via APIs..."
via diff show

MCP Server Mode

Via runs as an MCP server, exposing all commands as MCP tools. Source: [SPEC.md] This enables Claude Desktop, Cursor, and Windsurf to call Via tools natively. Source: [README.md]

Server Modes

via serve           # stdio (Claude Desktop, Cursor)
via serve --sse     # HTTP+SSE mode

Available MCP Tools

When running as an MCP server, the following tools are exposed: Source: [README.md]

Claude Desktop Configuration

{
  "mcpServers": {
    "via": { "command": "via", "args": ["serve"] }
  }
}

Or simply run via init, which automatically writes the MCP configuration. Source: [README.md]

Installation and Setup

Quick Start

Via requires Node.js >= 18 and can be installed or run with zero-install using npx: Source: [package.json] Source: [SPEC.md]

npx via --help

Initial Setup

via init           # writes MCP config for Claude Desktop, Cursor, Windsurf
via init --dry-run # preview what would be written

The init command detects installed AI tools and deploys a complete Via-wired setup to the current project, writing: Source: [SPEC.md]

• .cursor/rules/via-context.mdc — Cursor context injection rule
• .claude/CLAUDE.md — Claude context block
• ~/.via/config.json — updated with project
• via.config.json — project-level Via config

Preset Configurations

The scaffold command supports several presets: Source: [SPEC.md]

Data Storage Architecture

Local Storage Location

All local data is stored in ~/.via/: Source: [SPEC.md]

~/.via/
├── config.json             # user config, connected tools, preferences
├── tasks.db                # SQLite: task board
├── audit.db                # SQLite: compliance log
├── personas/               # .vpersona.json files per persona
├── spend/                  # usage logs per tool per day
└── handoffs/               # .vstate.json exports

Database Schema

The system uses SQLite for persistence with two primary databases: tasks.db for the task board and audit.db for the compliance log. Source: [SPEC.md]

Open Data Formats

Via uses open formats throughout. The .vstate.json handoff format includes: Source: [SPEC.md]

{
  "via_version": "0.1.0",
  "exported_at": "2026-05-10T12:00:00Z",
  "source_tool": "cursor",
  "current_task": "Refactor auth module — extract token validation",
  "open_questions": [
    "Should refresh tokens be stored in Redis or PostgreSQL?",
    "Do we need backward compat with v1 tokens?"
  ],
  "decisions": [
    { "at": "2026-05-10T11:30:00Z", "decision": "..." }
  ]
}

Vektor Ecosystem

Via is part of the Vektor ecosystem alongside Vex and Slipstream. Source: [README.md]

graph TD
    subgraph "Vektor Ecosystem"
        Vex[Vex<br/>Vector Exchange<br/>Migrate memory between vector stores]
        Via[Via<br/>Universal Integration Layer<br/>Route context across AI tools]
        Slipstream[Slipstream<br/>Intelligence Engine<br/>Graph memory, vector search]
    end
    
    Via --> Vex
    Via --> Slipstream

Upgrade Path

Via uses SQLite locally with no embeddings and no API calls for indexing. When you need semantic search, graph traversal, or team-shared context, you can upgrade to Vektor Slipstream. Source: [README.md]

Security and Privacy

Data Storage Policy

VEKTOR Memory does not store any of your data on their servers—for any product, open source or closed source. Your memories, credentials, and vault files live on your machine only. Source: [SECURITY.md]

This applies to:

• Vex (vector memory portability)
• Vek-Sync (MCP config sync, AES-256 credential vault)
• Via (CLI integration layer)
• VEKTOR Slipstream SDK
• Any future VEKTOR product

Security Measures

The project follows a strict security policy where vulnerabilities should be reported via email to [email protected] rather than opening a public GitHub issue. The team aims to respond within 7 days and will credit reporters by name or handle in release notes if they wish. Source: [SECURITY.md] Only the latest release receives security fixes. Source: [SECURITY.md]

Fraud Prevention Warning

The project explicitly states they will never contact users asking for personal information, AES-256 credential vault files or passwords, API keys, tokens, or licence keys, or any files stored or generated by VEKTOR tools. Source: [SECURITY.md]

Supported Tools and Versions

AI Tool Connectors

Via provides connectors for the following AI tools: Source: [SPEC.md] Source: [README.md]

Spend Tracking

The via spend command reads usage logs from all connected AI tools without making API calls—it reads local JSONL files that each tool writes natively. Source: [SPEC.md]

Supported sources:

• Claude Code: ~/.claude/projects/*.jsonl
• Cursor: ~/.cursor/usage/*.jsonl
• OpenAI: reads from OPENAI_LOG_DIR if set

The spend command includes leak detection patterns for verbose context re-injection, tool call loops, large file re-reads, and redundant fetches. Source: [SPEC.md]

Roadmaps and Future Development

Current Version (v0.1)

The initial release (v0.1.0) was published on 2026-05-10 with the following features: Source: [CHANGELOG.md]

• Initial release with all core commands
• ESM compatibility with top-level imports
• Native fetch usage (Node 18+)
• SSE server with proper response scoping
• Windows desktop notification support
• Cursor scaffold compatibility with Cursor >= 0.45

Planned Features (v0.2 and v0.3)

The roadmap includes: Source: [README.html]

Open Source and Licensing

Via is released under the Apache 2.0 license, which provides free forever usage rights. Source: [README.md] The project homepage is at https://github.com/Vektor-Memory/Via with bug reports accepted at the GitHub issues page or via email to [email protected]. Source: [package.json]

Funding is categorized as "other" with additional information available at https://vektormemory.com/downloads. Source: [package.json]

Getting Started Flow

graph LR
    A[Install via<br/>npx via] --> B[Initialize<br/>via init]
    B --> C{Detect<br/>AI Tools}
    C -->|Claude| D[Configure<br/>Claude Desktop MCP]
    C -->|Cursor| E[Create<br/>.cursor/rules]
    C -->|Windsurf| F[Setup<br/>Windsurf Config]
    D --> G[Ready to Use]
    E --> G
    F --> G
    G --> H[via serve<br/>Start MCP Server]

Related Pages

Related topics: Introduction to Via, MCP Server Integration

Quick Start Guide

Via is the universal integration layer for AI coding tools, enabling context and state sharing across Claude, Cursor, Windsurf, and ChatGPT. This guide walks you through installation, initial setup, and core workflows in under 10 minutes.

Prerequisites

Source: package.json:29

Installation

Via supports three installation methods. Choose the option that fits your workflow.

Option 1: Zero-Install (Recommended for Tryouts)

npx via <command>

No installation required. Downloads and runs the latest version on each invocation.

Option 2: Global npm Install

npm install -g @vektor/via

This installs the via command globally and enables tab completion.

Option 3: Project-Local Install

npm install @vektor/via

Useful for team projects where all developers should use the same Via version.

Source: README.md:35-45

Initial Setup with `via init`

The init command wires Via into every detected AI tool in a single command.

via init

What `via init` Does

graph TD
    A[via init] --> B{Detect AI Tools}
    B -->|Claude Code| C[Write .claude/CLAUDE.md]
    B -->|Cursor| D[Write .cursor/rules/via-context.mdc]
    B -->|Windsurf| E[Write Windsurf config]
    B -->|ChatGPT| F[Update ChatGPT instructions]
    C --> G[Create ~/.via/config.json]
    D --> G
    E --> G
    F --> G
    G --> H[Via Connected ✓]

Configuration Output

The command creates a global config at ~/.via/config.json:

{
  "version": "0.1.0",
  "tools": {
    "claude": { "enabled": true, "path": "~/.claude" },
    "cursor": { "enabled": true, "path": "~/.cursor" },
    "windsurf": { "enabled": true },
    "chatgpt": { "enabled": false }
  },
  "data_dir": "~/.via"
}

Project-Level Setup

For project-specific configuration, Via creates via.config.json:

{
  "project": "./my-project",
  "slipstream": false,
  "presets": ["solo-dev"]
}

Source: SPEC.md:5.5, commands/init.mjs

Core Commands Reference

After installation, these are the primary commands you'll use daily.

Source: CHANGELOG.md:8-18

Setting Up the MCP Server

The MCP server enables Claude Desktop, Cursor, and Windsurf to call Via tools natively.

Start the MCP Server

via serve           # stdio mode (default)
via serve --sse     # HTTP + Server-Sent Events mode

Configure Claude Desktop

Add to your Claude Desktop configuration file (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "via": {
      "command": "via",
      "args": ["serve"]
    }
  }
}

Available MCP Tools

When running as an MCP server, the following tools become available:

Source: commands/serve.mjs, README.md:95-115

Quick Workflows

Workflow 1: First-Time Project Setup

# 1. Initialize Via with all detected tools
via init

# 2. Add your codebase to memory
via memory add --file ./src/

# 3. Create your first task
via task add "Set up authentication" --high

# 4. Start the MCP server
via serve --sse

Workflow 2: Cross-Tool Context Sharing

# 1. Work in Cursor, make a decision
via log "Using JWT RS256 over HS256" --tool cursor

# 2. Export your current state
via handoff --export --task "Refactor auth module"

# 3. Switch to Claude Code, import state
via handoff --import ./handoffs/2026-05-10.vstate.json

# 4. Continue with full context intact

Workflow 3: Compare AI Tool Responses

# 1. Ask the same question to multiple tools
via diff "Explain microservices architecture"

# 2. Get Claude's response and log it
via diff add claude "Microservices split apps into small independent services..."

# 3. Get Cursor's response and log it
via diff add cursor "Microservices are small focused services that communicate via APIs..."

# 4. View comparison
via diff show

Source: README.md:55-85

Data Storage

Via stores all data locally in ~/.via/:

~/.via/
├── config.json          # User preferences and tool connections
├── tasks.db             # SQLite task board database
├── audit.db             # SQLite compliance log database
├── personas/            # Agent persona definitions (.vpersona.json)
├── spend/               # AI usage logs per tool per day
└── handoffs/            # Exported session states (.vstate.json)

Local-Only Architecture

Via uses SQLite locally by default. No embeddings are generated and no API calls are made for indexing.

Via uses SQLite locally. No embeddings, no API calls for indexing. When you need semantic search, graph traversal, or team-shared context — upgrade to Slipstream.

Source: README.md:120-125

Verify Installation

Run the status command to confirm everything is connected:

via status

Expected output:

Via v0.1.0 — Vektor Memory

  tools       claude ✓   cursor ✓   windsurf ✓   chatgpt –
  memory      local SQLite · 0 facts · last store never
  slipstream  not connected  →  npx via upgrade
  tasks       0 open · 0 in-progress · 0 done
  spend       today $0.00 · week $0.00
  audit       0 decisions logged

Source: SPEC.md:6.12

Next Steps

Troubleshooting

Tool Not Detected

# Force re-detection of all tools
via init --force

# Manually specify a tool path
via init --tool cursor --path ~/.cursor

MCP Server Won't Start

# Check Node.js version
node --version  # Must be >= 18

# Verify Via installation
via --version

# Run with debug output
DEBUG=via via serve

SQLite Errors

Via requires write access to ~/.via/. Verify permissions:

ls -la ~/.via/

Windows Desktop Notifications

If notifications don't appear, ensure node-notifier dependencies are installed. On Windows, this may require additional native modules.

Note: Windows desktop notification uses non-blocking BalloonTip instead of blocking MessageBox.

Source: CHANGELOG.md:22-23

Community and Support

Data Privacy: VEKTOR Memory does not store any of your data on their servers. All memories, credentials, and files live on your machine only.

Source: SECURITY.md

Related Pages

Related topics: Introduction to Via, AI Tool Connectors, Data Storage and Formats

System Architecture

Overview

Via is a universal CLI integration layer designed to connect multiple AI coding tools into a cohesive workflow ecosystem. The system architecture follows a modular, connector-based design that enables cross-tool context sharing, persistent state management, and standardized tooling access. At its core, Via acts as a bus between AI tools—routing context, managing tasks, and maintaining memory across sessions.

The architecture prioritizes local-first data storage using SQLite, avoiding external API dependencies for core functionality. When semantic search or graph traversal is required, users can upgrade to Vektor Slipstream.

Source: README.md

Related Pages

Related topics: System Architecture, MCP Server Integration, AI Tool Comparison (via diff)

AI Tool Connectors

Overview

AI Tool Connectors in Via are adapter modules that enable seamless integration between Via and various AI coding tools, agents, and platforms. Each connector abstracts the tool-specific mechanisms for reading usage logs, detecting session state, capturing decisions, and formatting context, providing a unified interface for cross-tool operations.

Source: SPEC.md - Repository Structure

The connector architecture embodies Via's core design principle: universal over specialized. Every connector exposes the same capability surface, allowing Via commands to operate identically regardless of which AI tool is running.

Source: SPEC.md - Design Principles

Architecture

Connector Directory Structure

Via/
├── connectors/
│   ├── claude.mjs          # Claude Code adapter
│   ├── cursor.mjs          # Cursor adapter
│   ├── windsurf.mjs        # Windsurf adapter
│   ├── chatgpt.mjs         # ChatGPT adapter
│   ├── langchain.mjs       # LangChain adapter
│   └── slipstream.mjs      # Slipstream upgrade bridge

Source: SPEC.md - Repository Structure

Design Pattern

Each connector follows a consistent pattern:

Source: SPEC.md - Design Principles

Connector Execution Flow

graph TD
    A[via CLI Command] --> B[Detect Tool via detect.mjs]
    B --> C{Is tool installed?}
    C -->|No| D[Skip connector]
    C -->|Yes| E[Load connector module]
    E --> F[Read session/usage data]
    F --> G[Format for Via standard]
    G --> H[Return unified response]
    
    I[via serve] --> J[MCP Server]
    J --> K[Route MCP tool call]
    K --> L[Invoke connector]
    L --> M[Return MCP-formatted response]

Source: README.md - MCP Server Mode

Supported Connectors

Claude Code Connector

The Claude connector interfaces with Anthropic's Claude Code CLI tool. It reads session data from Claude Code's project JSONL logs and formats context for injection into Claude Code sessions.

Session data source:

~/.claude/projects/*.jsonl

Capabilities:

• Session auto-capture for via log --scan and via log --watch
• Decision logging from Claude Code sessions
• Context block formatting for CLAUDE.md injection

Source: SPEC.md - via spend

Cursor Connector

The Cursor connector integrates with Cursor IDE. It reads usage logs and formats context for Cursor's rules system, specifically targeting Cursor's .cursor/rules/*.mdc file format introduced in version 0.45+.

Context files written:

.cursor/rules/via-context.mdc

Source: CHANGELOG.md - v0.1.0 Fixed

Capabilities:

• Usage log parsing from ~/.cursor/usage/*.jsonl
• Rules file generation for context injection
• Task state synchronization with Cursor's session

Windsurf Connector

The Windsurf connector provides integration with Codeium's Windsurf IDE, following the same patterns as the Cursor connector.

Capabilities:

• Session state detection
• Context formatting for Windsurf sessions
• Decision capture from Windsurf interactions

Source: README.md - Claude Desktop, Cursor, Windsurf support

ChatGPT Connector

The ChatGPT connector interfaces with OpenAI's ChatGPT CLI and web interface usage data.

Session data source:

OPENAI_LOG_DIR (if set)

Capabilities:

• Usage log parsing for via spend
• Cost tracking integration
• Context formatting for ChatGPT web/CLI sessions

Source: SPEC.md - via spend

LangChain Connector

The LangChain connector provides integration with LangChain-based agents and applications, enabling Via to track decisions and context within LangChain workflows.

Capabilities:

• LangChain agent session tracking
• Chain execution logging
• Memory context formatting

Source: README.md - MCP server with 8 tools

Slipstream Connector (Upgrade Bridge)

The Slipstream connector is a special upgrade bridge that, when configured, routes all memory operations through Vektor Slipstream instead of local SQLite. This connector is distinct from the tool adapters—it connects to the Slipstream intelligence engine.

Configuration requirements:

• Slipstream installed locally
• VEKTOR_API_KEY environment variable set

Source: SPEC.md - Slipstream upgrade bridge

Capabilities when Slipstream is active:

Source: SPEC.md - Slipstream upgrade bridge

ESM Compatibility

All connectors use ES modules (ESM) with top-level imports rather than require(). This ensures compatibility with Node.js 18+ and modern JavaScript tooling.

Implementation note from v0.1.0:

ESM compatibility: replaced require() with top-level imports in all connectors

Source: CHANGELOG.md - v0.1.0 Fixed

Version requirement:

Node.js >= 18

Source: package.json - engines

Native Dependencies

Connectors use Node.js native fetch (available in Node 18+) rather than the node-fetch polyfill.

Implementation note from v0.1.0:

Native fetch used throughout (Node 18+); removed node-fetch dependency

Source: CHANGELOG.md - v0.1.0 Fixed

Tool Detection

Via uses utils/detect.mjs to identify which AI tools are installed on the system before attempting to use their connectors.

graph LR
    A[User runs via command] --> B[detect.mjs scans common paths]
    B --> C{claude installed?}
    C -->|Yes| D[Mark claude available]
    C -->|No| E[Skip claude]
    D --> F{cursor installed?}
    F -->|Yes| G[Mark cursor available]
    F -->|No| H[Skip cursor]
    G --> I[... additional tools]

Source: SPEC.md - Repository Structure

Configuration Storage

Connector state and tool configuration are stored in the Via data directory:

~/.via/
├── config.json             # Connected tools, preferences
├── tasks.db                # SQLite: task board
├── audit.db                # SQLite: compliance log
├── personas/               # .vpersona.json files per persona
├── spend/                  # Usage logs per tool per day
└── handoffs/               # .vstate.json exports

Source: SPEC.md - Data Directory

Security Considerations

Via connectors operate entirely locally. No connector transmits data to external servers unless explicitly configured (such as the Slipstream connector when VEKTOR_API_KEY is set).

Data storage policy:

VEKTOR Memory does not store any of your data on our servers — for any product, open source or closed source. Your memories, credentials, and vault files live on your machine only.

Source: SECURITY.md - Data Storage Policy

Community Context and Usage Patterns

Based on community discussions, connectors address several key use cases:

MCP Universal Integration Layer

The Via connectors system enables what Reddit users describe as "a universal integration layer Cli tool" that connects multiple AI tools through MCP.

This one has a feature no other tool has ... Built an MCP tool that connects Qwen, Claude Code, Codex ...

Source: Reddit - A MCP universal integration layer Cli tool

Cross-Tool Session Management

The connectors enable a coding agent session manager that manages itself via its own MCP, allowing seamless handoffs between tools:

A coding agent session manager that manages itself via its own MCP ... workflow. You come back to PRs ready for merge.

Source: Reddit - A coding agent session manager

Why MCP Connectors Matter

Community discussions highlight that MCP-based connectors provide value when the agent needs to dynamically choose which tool to call:

mcp is worth it when the agent needs to pick which tool to call

Source: Reddit - why bothering with MCPs

Roadmap

Current (v0.3):

• Claude Code, Cursor, Windsurf connector support
• MCP server with 8 tools exposing connector functionality
• Local file conversion pipeline integration

Coming (v0.4):

• Team-shared task board via connectors
• via diff --live real-time comparison across tools
• Enhanced semantic search via Slipstream integration

Source: README.md - Roadmap

See Also

• Via CLI Commands — Commands that utilize connectors
• MCP Server Mode — Via as an MCP server exposing connector tools
• Slipstream Upgrade Bridge — Upgrade path for enhanced connector capabilities
• Vektor Ecosystem — Via, Vex, and Slipstream integration

Related Pages

Related topics: Data Storage and Formats, System Architecture, Task and Workflow Management

Memory System

Via's Memory System provides persistent, relationship-aware knowledge storage that works across all connected AI tools. Unlike traditional vector databases that rely on embeddings and cloud APIs, Via's memory operates entirely offline using SQLite, making it fast, private, and portable.

Overview

The Memory System serves as the central knowledge repository for the Via ecosystem. It captures facts, indexes codebases with full import relationships, and makes this information accessible to any AI tool connected via MCP.

Key characteristics:

Source: SPEC.md

Architecture

The Memory System comprises three primary command modules that work together to provide comprehensive knowledge management:

graph TD
    A[User / AI Tool] --> B[via memory Command]
    A --> C[via ingest Command]
    A --> D[via context Command]
    
    B --> E[SQLite Database]
    C --> E
    D --> E
    
    E --> F[Facts Table]
    E --> G[Codebase Index]
    E --> H[Import Graph]
    
    F --> I[Direct Matches]
    G --> I
    H --> J[Related via Imports]
    
    style E fill:#f9f,stroke:#333,stroke-width:2px
    style I fill:#bbf,stroke:#333
    style J fill:#bfb,stroke:#333

Core Components

Source: commands/memory.mjs, utils/db.mjs

Fact Storage

The simplest form of memory in Via is storing plain-text facts. These facts are persisted in SQLite and made available to all connected AI tools.

Storing Facts

via memory add "JWT tokens expire in 1h"
via memory add "API endpoint: /api/v2/users"
via memory add "Auth module uses RS256 signing"

Facts are stored with metadata including:

• Timestamp of creation
• Source tool (auto-detected or specified)
• Tags (optional)

Source: commands/memory.mjs:1-50

Listing Stored Facts

via memory list

This command displays all indexed files and stored facts with their timestamps and source information.

Source: README.md

Relationship-Aware Codebase Indexing

Via's most powerful feature is its ability to index codebases while preserving import relationships between files. This transforms simple keyword search into navigation through actual code architecture.

Supported Languages

The indexer extracts symbols and import edges from:

Source: commands/memory.mjs

Indexing a Codebase

via memory add --file ./src/

The indexing process:

1. Recursively scans the target directory
2. Parses each source file for symbols and imports
3. Builds an import graph in SQLite
4. Stores file metadata for quick lookup

Search with Relationship Traversal

When you search for a term, Via returns both direct matches and files that import them:

┌─ MEMORY — SEARCH: auth ───────────────────────
│
│  Direct matches (2 files)
│    ● auth.js       ./src/auth.js
│    ● config.js     ./src/config.js
│
│  Related via imports (3 files)
│    ○ server.js     ./src/server.js
│    ○ middleware.js ./src/middleware.js
│    ○ routes.js     ./src/routes/auth.js
└───────────────────────────────────────────────

Source: README.md

Import Graph Visualization

via memory graph

Displays the import relationships between files, showing how code is connected architecturally rather than just textually.

Source: README.md

Universal Knowledge Ingestion

The via ingest command provides a universal intake pipeline for external knowledge sources.

Supported Sources

Source: SPEC.md

Ingestion Pipeline

graph LR
    A[Source Input] --> B{Type Detection}
    B -->|URL| C[HTTP Fetch]
    B -->|File| D[Local Read]
    B -->|Directory| E[Recursive Walk]
    
    C --> F[Content Extraction]
    D --> F
    E --> F
    
    F --> G[Chunking]
    G --> H[SQLite Storage]
    H --> I[Available via via context]

Usage Examples

# Ingest a URL
via ingest https://example.com/api-docs

# Ingest a file
via ingest ./docs/architecture.md

# Ingest a directory
via ingest ./docs/

# Ingest and convert to markdown
via ingest ./report.pdf --to md

Source: commands/ingest.mjs, SPEC.md

Context Formatting

The via context command pulls formatted memory context for use by AI tools. It formats stored facts and codebase information according to each tool's conventions.

Supported Tool Formats

Source: commands/context.mjs

Output Format Example

via context "auth module"

Returns a formatted block containing:

• Direct matches from memory search
• Related files via import graph
• Recent facts tagged with relevant keywords

Source: SPEC.md

Slipstream Upgrade Path

Via's memory operates fully offline with SQLite at the local tier. The Slipstream upgrade provides enhanced capabilities:

Feature Comparison

Source: SPEC.md

Upgrade Command

npx via upgrade

This connects your local Via installation to Slipstream, enabling semantic search and team features.

Source: CHANGELOG.md

MCP Integration

The Memory System exposes its functionality through MCP tools, making it accessible to AI agents running in Claude Desktop, Cursor, and other MCP-compatible tools.

Available MCP Tools

Source: README.md

Configuration

Via's MCP server is configured automatically when you run:

via init

This writes the necessary MCP configuration to:

• Claude Desktop: ~/.claude/projects/*/mcp.json
• Cursor: .cursor/rules/

Source: README.md

Data Storage

All memory data is stored locally in SQLite. The database file location and schema ensure portability across machines when synced via via sync.

Database Schema (Conceptual)

Source: utils/db.mjs

Privacy Model

Via's architecture guarantees that all memory data remains local:

• No API calls for indexing — all processing happens on-device
• No data sent to external servers — memory is your local SQLite
• Portable formats — .vstate.json for handoff, SQLite for storage

Source: SECURITY.md

Command Reference

`via memory add`

Store a fact or index a codebase.

via memory add "JWT tokens expire in 1h"          # store a fact
via memory add --file ./src/                      # index a codebase

`via memory search`

Search stored facts and codebase with relationship traversal.

via memory search "auth"                          # search + related files

`via memory graph`

Display import relationships as a visual graph.

via memory graph                                  # show import relationships

`via memory list`

List all indexed files and stored facts.

via memory list                                   # list indexed files + facts

`via ingest`

Universal knowledge intake pipeline.

via ingest <url|file|directory>                   # ingest content

`via context`

Format memory context for a specific AI tool.

via context "query"                               # pull formatted context

Source: commands/memory.mjs, README.md

Roadmap

v0.3 (Current)

• Relationship-aware codebase indexing with import graph in SQLite
• Local fact storage and search
• Ingestion from URLs, files, and directories

v0.4 (Coming)

• via memory search semantic upgrade via Slipstream
• Team-shared memory board
• Enhanced relationship traversal

Source: README.md

Related Pages

Related topics: AI Tool Connectors

AI Tool Comparison (via diff)

Overview

The via diff command is Via's signature feature for comparing responses from different AI coding tools side-by-side. It enables developers to evaluate how different AI assistants approach the same problem, revealing agreements, divergences, and unique terminology each tool contributes. This capability has been identified by the community as "a feature no other tool has." Source: Reddit - LocalLLaMA

Purpose and Scope

The comparison engine serves multiple use cases:

Source: README.md

Architecture

Data Flow

graph TD
    A[User Query] --> B[via diff "prompt"]
    B --> C{Register Response}
    C --> D[via diff add claude "response"]
    C --> E[via diff add cursor "response"]
    D --> F[SQLite: comparisons.db]
    E --> F
    F --> G[via diff show]
    G --> H[Side-by-side Display]
    G --> I[Similarity Analysis]
    G --> J[Unique Terms Extraction]

Comparison Process

The comparison engine performs three distinct analyses:

1. Word Count Metrics — Counts tokens/words per response
2. Overlap Calculation — Measures word-level similarity percentage
3. Term Extraction — Identifies unique vocabulary each tool contributed

Source: README.md

Commands Reference

Primary Commands

Source: README.md

Supported Tools

The comparison engine is tool-agnostic. Any AI tool can be compared:

• Claude / Claude Code
• Cursor
• Codex
• Windsurf
• Custom tool names (strings)

Source: README.md

Usage Examples

Basic Comparison Workflow

# 1. Register the prompt you want to compare
via diff "explain microservices"

# 2. Store Claude's response
via diff add claude "Microservices split apps into small independent services..."

# 3. Store Cursor's response
via diff add cursor "Microservices are small focused services that communicate via APIs..."

# 4. Display the comparison
via diff show

Source: README.md

Example Output

┌─ DIFF — explain microservices ────────────────
│ claude          12 words
│ cursor          14 words
│ similarity      21% word overlap
│
│  claude                          |  cursor
│  ──────────────────────────────  │  ──────────────────────────────
│  Microservices split apps into   │  Microservices are small focused
│  small independent services...   │  services that communicate via...
│
│ claude unique terms  independent, database
│ cursor unique terms  focused, communicate, deployed
└───────────────────────────────────────────────

Source: README.md

Listing Saved Comparisons

via diff list

Displays all previously saved comparisons for review and re-comparison.

Source: README.md

Output Components

Display Elements

Source: README.md

Data Model

Comparison Storage

Comparisons are stored locally in SQLite. The schema captures:

• Prompt text
• Tool name
• Response text
• Timestamp
• Word counts
• Calculated similarity

Open Format Support

Via stores comparisons in an open format accessible to other tools via MCP, enabling integration with broader AI agent workflows.

Source: SPEC.md

Integration with MCP Server

When running as an MCP server via via serve, the diff functionality is exposed as MCP tools for programmatic access:

via serve           # stdio mode for Claude Desktop, Cursor
via serve --sse     # HTTP+SSE mode for remote connections

Source: README.md

Roadmap

v0.3 (Coming)

Source: README.md

Best Practices

1. Consistent Prompts — Use identical prompt text when comparing tools to ensure valid comparison
2. Multiple Iterations — Run the same comparison multiple times as AI tools have non-deterministic output
3. Combine with via ask — Use via ask to route questions before comparing responses
4. Review Unique Terms — Focus on unique vocabulary to understand each tool's reasoning approach

Related Commands

Source: README.md

Limitations

• Word-level similarity only — Current implementation uses word overlap, not semantic similarity
• No automatic tool invocation — Responses must be manually added via via diff add
• Local storage — Comparisons are local to the machine; no team sharing built-in
• No streaming comparison — Must wait for full responses before comparison

Source: SPEC.md

Related Pages

Related topics: Memory System, Data Storage and Formats

File Conversion Pipeline

Via's file conversion pipeline provides universal local file format conversion without cloud uploads. All processing happens entirely on the local machine, leveraging external command-line tools for format transformation.

Overview

The via convert command transforms files between formats using native system tools. It integrates directly with Via's memory system through optional ingestion, allowing converted content to be stored and searched within the local knowledge base.

Key Characteristics

Architecture

graph TD
    A[User Input] --> B[via convert Command]
    B --> C{Tool Check}
    C -->|Missing| D[Error + Install Guide]
    C -->|Available| E[Format Detection]
    E --> F[External Tool Dispatch]
    F --> G[FFmpeg / ImageMagick / Pandoc / LibreOffice / Poppler / 7-Zip]
    G --> H{--ingest flag?}
    H -->|Yes| I[Memory Pipeline]
    H -->|No| J[Output File]
    I --> K[SQLite Storage]
    J --> K

Supported Formats

Images

Image conversion relies on ImageMagick for the heavy lifting.

Audio

Audio processing uses FFmpeg.

Video

Video conversion supports extraction of audio tracks (to mp3) and animation conversion (to gif).

Documents

Document conversion uses Pandoc as the primary processor.

Office Files

Office document processing requires LibreOffice.

PDF

PDF text extraction uses Poppler's pdftotext utility.

Archives

Archive creation uses standard Unix tools plus 7-Zip for compressed archives.

External Tool Requirements

The conversion pipeline depends on several system utilities. Via provides a built-in tool check to verify availability.

via convert --check

Tool Matrix

Command Reference

Basic Conversion

via convert <file> --to <format>

Converts a single file to the specified format. The output is written to the current directory with the original filename and new extension.

Example:

via convert ./report.pdf --to md
# Output: ./report.md

Conversion with Memory Ingestion

via convert <file> --to <format> --ingest

After successful conversion, the resulting content is stored in Via's local SQLite memory database. This enables subsequent searches via via memory search.

Example:

via convert ./report.pdf --to md --ingest
# Converts to markdown and stores in memory

Tool Availability Check

via convert --check

Validates that all required external tools are installed and accessible. Returns a formatted table showing which tools are installed.

Output:

┌─ CONVERT — TOOL CHECK ────────────────────────
│ FFmpeg          installed  audio/video
│ ImageMagick     installed  images
│ Pandoc          installed  documents
│ LibreOffice     installed  office docs
│ Poppler         installed  pdf→txt
│ Zip             installed  archives
│ 7-Zip           installed  7z archives
└───────────────────────────────────────────────

Format Discovery

via convert --formats

Lists all supported input and output formats grouped by category.

Memory Pipeline Integration

When --ingest is specified, converted content flows into Via's memory system:

graph LR
    A[File Input] --> B[Conversion]
    B --> C[Text Content]
    C --> D[Chunking]
    D --> E[SQLite Storage]
    E --> F[via memory search]

Memory Storage Behavior

• Text-based formats (md, txt, html): Full content stored with keyword indexing
• Binary formats (pdf, images): Extracted text content stored when possible
• No embeddings: Uses keyword-based search only in local mode

Configuration

File conversion settings are stored in ~/.via/config.json:

{
  "convert": {
    "defaultOutputDir": ".",
    "overwrite": false
  }
}

Troubleshooting

Missing Tools

If --check reports missing tools, install them via your system package manager:

macOS:

brew install ffmpeg imagemagick pandoc libreoffice poppler p7zip

Ubuntu/Debian:

apt-get install ffmpeg imagemagick pandoc libreoffice poppler-utils p7zip-full

Windows: Use chocolatey or scoop to install equivalent packages.

Conversion Failures

Workflow Examples

Document Processing Pipeline

# Convert office doc to PDF for sharing
via convert ./proposal.docx --to pdf

# Convert and ingest for knowledge base
via convert ./whitepaper.pdf --to md --ingest

# Search converted content later
via memory search "architecture"

Asset Preparation

# Extract audio from video
via convert ./interview.mp4 --to mp3

# Convert video to animated gif
via convert ./demo.mov --to gif

# Batch image optimization
via convert ./assets/*.png --to webp

Relationship to Other Commands

The file conversion pipeline works alongside other Via commands:

Technical Notes

No Cloud Dependencies

The entire conversion pipeline operates locally. This design choice:

• Ensures privacy for sensitive documents
• Eliminates API rate limits
• Reduces latency for large files
• Works offline

Slipstream Upgrade Path

Local conversion defaults to keyword-based memory storage. When connected to Slipstream (Vektor's vector search engine), the converted content becomes available for semantic search and graph traversal. Upgrade via npx via upgrade.

Source: README.md Source: SPEC.md Source: CHANGELOG.md

Related Pages

Related topics: Introduction to Via, MCP Server Integration, Data Storage and Formats

Task and Workflow Management

Via provides a comprehensive task and workflow management system that bridges multiple AI coding tools. This system enables persistent task tracking, session handoff between tools, unified activity logging, and intelligent task routing—all stored locally with SQLite for privacy.

Overview

Via's workflow management architecture consists of five core commands that work together to maintain context across AI tool sessions:

This architecture ensures that work context persists regardless of which AI tool you're currently using. Source: SPEC.md

Task Management System

Core Task Operations

The via task command provides a complete task lifecycle management system backed by SQLite. Tasks can be created, listed, updated, started, completed, and deleted through both CLI and MCP interfaces. Source: commands/task.mjs

#### Task Subcommands

#### Task Data Model

Each task in Via maintains the following fields:

{
  "id": "integer PRIMARY KEY",
  "title": "string NOT NULL",
  "status": "open | in-progress | done | blocked",
  "priority": "low | medium | high | critical",
  "tool": "string (source AI tool)",
  "persona": "string (assigned persona)",
  "created_at": "ISO8601 timestamp",
  "updated_at": "ISO8601 timestamp",
  "notes": "string (additional context)"
}

Source: SPEC.md:6.3

#### Usage Examples

# Add a high-priority task
via task add "refactor auth module" --high

# List all tasks
via task

# Mark task as done
via task done <id>

# Start working on a task
via task start <id>

MCP Task Tools

When Via runs as an MCP server, it exposes task management as tools that any connected AI tool can call:

This enables AI tools like Claude Code, Cursor, and Windsurf to read and update the shared task board natively. Source: README.md

Multi-Tool Task Visibility

The task board is designed for cross-tool visibility. Any connected AI tool can read the same board via MCP, ensuring that:

• Tasks created in Claude Code are visible to Cursor
• Completed tasks in one tool show as done in others
• Task context survives session boundaries

┌─────────────────────────────────────────────────────────┐
│                  Shared Task Board                      │
├─────────────────────────────────────────────────────────┤
│  Claude Code ←→ Cursor ←→ Windsurf ←→ ChatGPT         │
│       ↓              ↓         ↓            ↓          │
│    Read/Write     Read/Write  Read/Write   Read/Write   │
│       └──────────────┴──────────┴─────────────┘        │
│                      SQLite                             │
└─────────────────────────────────────────────────────────┘

Activity Logging System

The `via log` Command

Unified activity logging captures decisions, events, and session activity across all connected AI tools. This creates a searchable audit trail that persists beyond individual sessions. Source: commands/log.mjs

#### Log Subcommands

Session Auto-Capture

Via automatically captures Claude Code sessions by monitoring session files at ~/.claude/projects/*.jsonl. When sessions complete, events are logged to the unified activity log. Source: README.md

# Log a decision with manual tool specification
via log "decided to use postgres" --tool claude

# Scan all existing sessions
via log --scan

# Watch for new sessions in real-time
via log --watch

# View today's activity
via log --today

# Search logs for specific content
via log search "postgres"

Audit Compliance Logging

The via audit subsystem maintains an append-only compliance log with tool, timestamp, and rationale for every decision. Source: SPEC.md:6.8

┌─ AUDIT EXPORT FORMATS ──────────────────────
│  JSONL    jsonl    machine-readable
│  CSV      csv      spreadsheet-compatible
│  Markdown markdown  human-readable reports
└─────────────────────────────────────────────

Session Handoff System

The `via handoff` Command

The handoff system enables complete session state export and import, allowing seamless transitions between AI tools without losing context. Source: commands/handoff.mjs

#### Handoff Workflow

graph LR
    A[Claude Code] -->|via handoff --export| B[.vstate.json]
    B -->|via handoff --import| C[Cursor]
    C -->|continues| D[Sprint Work]

#### Export Operations

# Export current session state
via handoff --export

# Include current task description
via handoff --export --task "Refactor auth module"

# Specify source tool
via handoff --export --tool cursor

#### Import Operations

# Import session state from file
via handoff --import ./sprint3.vstate.json

# Format output for target tool
via handoff --import ./sprint3.vstate.json --to claude

# Print formatted context block for manual pasting
via handoff --import ./sprint3.vstate.json --print

Session State File Format

The .vstate.json format captures complete working state:

{
  "via_version": "0.1.0",
  "exported_at": "2026-05-10T12:00:00Z",
  "source_tool": "cursor",
  "current_task": "Refactor auth module — extract token validation",
  "open_questions": [
    "Should refresh tokens be stored in Redis or PostgreSQL?",
    "Do we need backward compat with v1 tokens?"
  ],
  "decisions": [
    {
      "at": "2026-05-10T11:30:00Z",
      "decision": "Use JWT RS256 not HS256",
      "rationale": "Multi-service verification"
    }
  ],
  "files_in_context": [
    "src/auth/index.ts",
    "src/auth/tokens.ts"
  ],
  "next_action": "Write unit tests for validateToken()",
  "persona": "senior-dev",
  "memory_refs": []
}

Source: SPEC.md:5.1

Intelligent Task Routing

The `via ask` Command

Route questions to the most appropriate AI tool based on task type, cost, and capabilities. Source: commands/ask.mjs

# Auto-route to recommended tool (opens tool automatically)
via ask "should I use postgres or sqlite?"

# Force routing to specific tool
via ask "refactor auth module" --tool cursor

# Get recommendation only (don't open tool)
via ask "explain this architecture" --no-open

Routing Logic

The routing system uses rule-based decision making in v0.1:

Future versions will incorporate ML routing based on spend/outcome history. Source: SPEC.md:6.11

Response Comparison

The `via diff` Command

Compare how different AI tools respond to the same prompt. Useful for understanding tool-specific approaches and selecting the best response. Source: commands/diff.mjs

#### Diff Workflow

graph TD
    A[via diff "prompt"] --> B[Store prompt]
    B --> C[via diff add claude "response"]
    C --> D[via diff add cursor "response"]
    D --> E[via diff show]
    E --> F[Side-by-side comparison]

#### Usage Examples

# Register a new comparison prompt
via diff "explain microservices"

# Store Claude's response
via diff add claude "Microservices split apps into small independent services..."

# Store Cursor's response
via diff add cursor "Microservices are small focused services that communicate via APIs..."

# Display comparison
via diff show

# List all saved comparisons
via diff list

#### Diff Output Format

┌─ DIFF — explain microservices ───────────────
│ claude          12 words
│ cursor          14 words
│ similarity      21% word overlap
│
│  claude                          |  cursor
│  ──────────────────────────────  |  ──────────────────────────────
│  Microservices split apps into   |  Microservices are small focused
│  small independent services...   |  services that communicate via...
│
│ claude unique terms  independent, database
│ cursor unique terms  focused, communicate, deployed
└──────────────────────────────────────────────

Slipstream Integration

When Via is connected to Slipstream (via the VEKTOR_API_KEY environment variable), the task and workflow management system gains enhanced capabilities:

Source: SPEC.md:8

Data Storage

Local SQLite Database

All task data is stored in ~/.via/tasks.db using SQLite for privacy. No data leaves the local machine. Source: lib/db.mjs

Directory Structure

~/.via/
├── config.json      # User configuration
├── tasks.db         # SQLite: task board
├── audit.db         # SQLite: compliance log
├── personas/        # .vpersona.json files
├── spend/           # Usage logs per tool
└── handoffs/        # .vstate.json exports

Community Context

Users have expressed strong interest in workflow management features:

• MCP Integration: Via's MCP server capabilities allow AI tools to manage themselves via MCP, as discussed in r/ClaudeAI discussions
• Cross-Tool Orchestration: The ability to manage coding agent sessions across multiple tools has been highlighted as a key differentiator
• Universal MCP Layer: The Reddit community noted that Via's universal MCP integration layer connects multiple AI tools in ways other tools haven't achieved

Quick Reference

Common Workflow Sequences

Starting a New Task with Claude Code and Switching to Cursor:

# In Claude Code
via task add "Build user authentication" --high
via log "Using NextAuth for auth flow"
# ... complete some work ...
via handoff --export --task "Build user authentication"

# In Cursor
via handoff --import ~/handoffs/latest.vstate.json
via task start <id>

Comparing Tool Responses:

via diff "implement rate limiting"
via diff add claude "Rate limiting can be implemented..."
via diff add cursor "Here's a rate limiting implementation..."
via diff show

Status Output

The via status command provides a quick health check including task metrics:

via status

Output:

Via v0.1.0 — Vektor Memory

  tools       claude ✓   cursor ✓   windsurf ✓   chatgpt –
  tasks       3 open · 1 in-progress · 12 done
  audit       47 decisions logged

Related Pages

Related topics: Introduction to Via, AI Tool Connectors, Quick Start Guide

MCP Server Integration

Via functions as an MCP (Model Context Protocol) server, exposing its core functionality as MCP tools that AI tools like Claude Code, Cursor, and Windsurf can invoke natively. This integration enables Via to act as a universal context and state bus across multiple AI tools without requiring manual CLI execution.

Overview

The MCP server implementation allows Via to:

• Expose all 12 Via commands as MCP tools
• Serve as a bridge between different AI tools via a shared MCP interface
• Enable AI agents to manage tasks, memories, and context without leaving their native environment
• Support both local (stdio) and remote (HTTP+SSE) connection modes

Source: SPEC.md:7

Architecture

Connection Modes

Via supports two MCP server modes:

graph TD
    A[Claude Code / Cursor / Windsurf] -->|stdio| B[Via MCP Server]
    A2[Remote AI Tool] -->|HTTP + SSE| B
    B --> C[SQLite Local Storage]
    B --> D[Slipstream (Optional)]
    
    E[Task Board] --> C
    F[Memory Store] --> C
    G[Audit Log] --> C
    
    style B fill:#e1f5fe
    style C fill:#f3e5f5

MCP Tool Naming Convention

All MCP tools follow a consistent naming pattern derived from Via's command structure:

via_<command>_<subcommand>

Source: SPEC.md:7

Available MCP Tools

Core Tools

Source: README.md, SPEC.md:6.12

Tool Discovery

When running as an MCP server, Via automatically discovers and registers all available tools based on the command modules present in the commands/ directory. This modular approach allows for extensibility without modifying the core server implementation.

Configuration

Claude Desktop Configuration

To connect Via to Claude Desktop, add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "via": {
      "command": "via",
      "args": ["serve"]
    }
  }
}

Alternatively, run via init to automatically configure MCP connections for all detected AI tools.

Source: README.md, SPEC.md:6.6

SSE Mode Configuration

For remote connections requiring HTTP+SSE transport:

via serve --sse

This starts the MCP server on an available port, listening for incoming connections over HTTP with Server-Sent Events for bidirectional communication.

Implementation Details

Entry Point

The MCP server is initialized through the main via.mjs entry point when the serve subcommand is invoked:

// via.mjs - Simplified serve command routing
if (cmd === 'serve') {
  const { serve } = await import('./commands/serve.mjs');
  return serve(args);
}

Source: via.mjs, CHANGELOG.md:26

Module Structure

The MCP server implementation follows Via's consistent module conventions:

Via/
├── commands/
│   └── serve.mjs          # MCP server command implementation
├── connectors/
│   ├── claude.mjs         # Claude Code connector
│   ├── cursor.mjs         # Cursor connector
│   └── slipstream.mjs     # Slipstream upgrade bridge
└── utils/
    ├── db.mjs              # SQLite adapter for data persistence
    └── format.mjs          # Output formatting utilities

Source: SPEC.md:3

Workflow Examples

Task Management Workflow

sequenceDiagram
    participant C as Claude Code
    participant V as Via MCP Server
    participant DB as SQLite
    
    C->>V: via_task_add("Refactor auth module")
    V->>DB: INSERT INTO tasks (...)
    DB-->>V: task_id: 42
    V-->>C: { id: 42, status: "open" }
    
    C->>V: via_task_list()
    V->>DB: SELECT * FROM tasks WHERE status != 'done'
    DB-->>V: [tasks...]
    V-->>C: Formatted task list
    
    C->>V: via_task_done(42)
    V->>DB: UPDATE tasks SET status = 'done'
    DB-->>V: success
    V-->>C: Task marked complete

Context Retrieval Workflow

graph LR
    A[AI Tool Request] --> B[via_context tool]
    B --> C{Local SQLite or Slipstream?}
    C -->|Local| D[Keyword FTS Search]
    C -->|Slipstream| E[BM25 + Semantic + Graph]
    D --> F[Formatted Context Block]
    E --> F
    F --> G[AI Tool Context]

Features and Capabilities

Cross-Tool Compatibility

The MCP server exposes tools that work identically across all supported AI tools:

• Claude Code: Native MCP integration via stdio
• Cursor: Via .cursor/rules/via-context.mdc rules file
• Windsurf: Standard MCP client support
• ChatGPT: Via connector module

Source: SPEC.md:3, CHANGELOG.md:34

Slipstream Integration

When Slipstream is installed and configured (VEKTOR_API_KEY set), the MCP server routes memory operations through Slipstream's enhanced engine:

Source: SPEC.md:8

Security Considerations

Via's MCP server operates entirely locally. Key security points:

• No data is transmitted to external servers unless using remote SSE mode with explicit configuration
• Slipstream upgrade is transparent but requires explicit opt-in
• All data stored in ~/.via/ remains under user control
• The server does not expose administrative functions to connected tools

Source: SECURITY.md

Troubleshooting

Common Issues

Health Check

Run via status to verify MCP server connectivity and tool registration:

via status

Expected output includes MCP tool registration status and connected tool health indicators.

Source: SPEC.md:6.12

Version History

Source: CHANGELOG.md, package.json:4

See Also

• Via Command Reference — Complete list of Via commands
• Slipstream Integration — Upgrade path for enhanced memory
• Vektor Ecosystem — Related Vektor Memory products

Related Pages

Related topics: System Architecture, Memory System

Data Storage and Formats

Via implements a local-first data storage architecture that prioritizes user privacy and offline capability. All data remains on the user's machine, with no external API calls for storage operations. The system uses SQLite for relational data and structured JSON files for portable configurations and cross-tool handoffs.

Architecture Overview

Via stores all persistent data within a single directory (~/.via/) and uses two primary storage mechanisms:

graph TD
    A[~/.via/] --> B[SQLite Databases]
    A --> C[JSON Configuration]
    A --> D[Persona Files]
    A --> E[Spend Logs]
    A --> F[Handoff Exports]
    
    B --> B1[tasks.db]
    B --> B2[audit.db]
    
    C --> C1[config.json]
    
    D --> D1[*.vpersona.json]
    
    E --> E1[*.jsonl per tool/day]
    
    F --> F1[*.vstate.json]

The architecture follows a clear separation of concerns:

*Source: SPEC.md*

Directory Structure

All Via data resides in ~/.via/ with the following organization:

~/.via/
├── config.json             # Global configuration, connected tools
├── tasks.db                # SQLite task board database
├── audit.db                # SQLite compliance log database
├── personas/               # Named persona definitions
│   ├── developer.vpersona.json
│   └── cto.vpersona.json
├── spend/                  # Usage logs from connected AI tools
│   ├── claude/
│   │   ├── 2026-01-15.jsonl
│   │   └── 2026-01-16.jsonl
│   └── cursor/
│       └── 2026-01-15.jsonl
└── handoffs/               # Exported session states
    └── 2026-05-10T12-00-00.vstate.json

*Source: SPEC.md*

SQLite Databases

Via uses sql.js (a JavaScript port of SQLite) for relational data storage, enabling pure JavaScript database operations without native dependencies.

Task Database (tasks.db)

The task board stores persistent tasks that any connected AI tool can access via MCP.

graph LR
    A[via task add] --> B[tasks.db]
    A2[Claude Code] --> B
    A3[Cursor] --> B
    B --> C[via task list]
    B --> D[via task done]

Schema:

*Source: commands/task.mjs*

Available Operations:

via task add "refactor auth module" --high
via task list
via task update <id> --status in-progress
via task done <id>
via task delete <id>
via task next    # Get next actionable task

Audit Database (audit.db)

The compliance log maintains an append-only record of AI decisions and rationales.

*Source: commands/audit.mjs*

Export Formats:

• jsonl — JSON Lines (newline-delimited JSON)
• csv — Comma-separated values
• markdown — Formatted markdown table

via audit log "Chose PostgreSQL over MongoDB for user data"
via audit list --tool claude
via audit export --format csv --output ./audit-2026.csv
via audit search "authentication"

Configuration Format

Global Configuration (config.json)

Located at ~/.via/config.json, this file stores user preferences and connected tool configurations.

{
  "version": "0.1.0",
  "tools": {
    "claude": { "enabled": true, "path": "~/.claude" },
    "cursor": { "enabled": true, "path": "~/.cursor" },
    "windsurf": { "enabled": false },
    "chatgpt": { "enabled": false }
  },
  "slipstream": {
    "connected": false,
    "url": null
  },
  "preset": "solo-dev",
  "notifications": {
    "desktop": true,
    "slack": null,
    "discord": null
  },
  "sync": {
    "github_repo": null,
    "last_backup": null
  }
}

*Source: utils/config.mjs*

Project Configuration (via.config.json)

Project-level configuration stored in the repository root:

{
  "project": "my-app",
  "preset": "startup-team",
  "memory": {
    "index_paths": ["./src", "./docs"],
    "exclude": ["node_modules", ".git"]
  },
  "personas": ["developer", "reviewer"]
}

*Source: SPEC.md*

Open Formats

Session Handoff Format (.vstate.json)

The session handoff format enables transferring working state between AI tools and machines.

{
  "via_version": "0.1.0",
  "exported_at": "2026-05-10T12:00:00Z",
  "source_tool": "cursor",
  "current_task": "Refactor auth module — extract token validation",
  "open_questions": [
    "Should refresh tokens be stored in Redis or PostgreSQL?",
    "Do we need backward compat with v1 tokens?"
  ],
  "decisions": [
    {
      "at": "2026-05-10T11:30:00Z",
      "decision": "Use JWT with 1h expiry",
      "rationale": "Simpler than session-based, sufficient for API auth"
    }
  ],
  "memory_context": {
    "facts": ["JWT expires in 1h", "Auth uses bcrypt"],
    "recent_files": ["./src/auth.js", "./src/middleware.js"]
  }
}

*Source: commands/handoff.mjs*

Usage:

via handoff --export                        # Save to ~/.via/handoffs/<timestamp>.vstate.json
via handoff --import ./sprint3.vstate.json  # Restore on any machine
via handoff --task "Refactor auth" --tool cursor
via handoff --print                         # Print formatted context block

Persona Format (.vpersona.json)

Named agent personas stored as portable JSON files in ~/.via/personas/.

{
  "name": "cto",
  "system_prompt": "You are the CTO making technical decisions...",
  "memory_namespace": "cto-context",
  "preferences": {
    "code_style": "enterprise",
    "documentation": "required",
    "testing": "tdd"
  },
  "tool_affinity": ["claude", "cursor"],
  "created_at": "2026-05-01T10:00:00Z"
}

*Source: commands/persona.mjs*

Persona Commands:

via persona create cto --prompt "You are a CTO..."
via persona use cto --in cursor    # Output formatted for Cursor
via persona list
via persona show cto
via persona delete cto

Spend Data Format

Usage logs from connected AI tools stored as JSONL (JSON Lines) files.

Claude Code Format

Via reads from ~/.claude/projects/*.jsonl:

{"timestamp":"2026-01-15T14:30:00Z","model":"claude-opus-4-5","input_tokens":1200,"output_tokens":850,"cost":0.015}
{"timestamp":"2026-01-15T14:35:00Z","model":"claude-opus-4-5","input_tokens":2100,"output_tokens":1200,"cost":0.028}

Cursor Format

Via reads from ~/.cursor/usage/*.jsonl:

{"timestamp":"2026-01-15T10:00:00Z","model":"cursor-3-5-sonnet","input_tokens":800,"output_tokens":600,"cost":0.012}

*Source: commands/spend.mjs*

Spend Commands:

via spend today        # Today's spending
via spend week        # Current week
via spend month       # Current month
via spend session     # Current session only
via spend leaks       # Detect wasteful patterns
via spend export      # Export to CSV

Data Flow

graph TD
    subgraph Input
        T1[Claude Code]
        T2[Cursor]
        T3[Windsurf]
    end
    
    subgraph Via
        DB[(tasks.db)]
        AUDIT[(audit.db)]
        CFG[config.json]
        PERSONA[personas/]
        SPEND[spend/]
    end
    
    subgraph MCP
        MCP1[via_task_list]
        MCP2[via_memory_search]
        MCP3[via_log]
        MCP4[via_context]
    end
    
    T1 -->|JSONL logs| SPEND
    T2 -->|JSONL logs| SPEND
    T1 -->|via task| DB
    T2 -->|via task| DB
    T1 -->|via audit| AUDIT
    T2 -->|via audit| AUDIT
    T3 -->|via task| DB
    
    DB --> MCP1
    CFG --> MCP2
    AUDIT --> MCP3
    PERSONA --> MCP4

Database Utilities

The utils/db.mjs module provides the core database functionality:

// Initialize or open SQLite database
const db = initDb('tasks');

// Query with automatic error handling
const tasks = db.exec(
  'SELECT * FROM tasks WHERE status = ?',
  ['open']
);

// Insert with parameterized queries
db.run(
  'INSERT INTO tasks VALUES (?, ?, ?, ?, ?, ?, ?)',
  [id, title, 'open', tool, persona, created_at, updated_at]
);

*Source: utils/db.mjs*

Key Features:

• Pure JavaScript SQLite via sql.js
• Automatic database initialization
• Parameterized queries for security
• Transaction support for bulk operations
• Automatic schema migrations

Privacy Architecture

Via's data storage is designed with privacy as a core principle:

All data remains local. No VEKTOR servers receive, store, or process any user data. This is enforced architecturally, not merely policy.

*Source: SECURITY.md*

Slipstream Upgrade Path

The local SQLite storage represents the "Slipstream ceiling" for Via's base tier:

Users requiring semantic search, graph traversal, or team-shared context can upgrade to Vektor Slipstream while maintaining compatibility with existing Via data.

*Source: SPEC.md*

Summary

Via's data storage architecture provides:

1. Local-first storage — All data stays on your machine in ~/.via/
2. SQLite relational databases — Tasks and audit logs with full query capability
3. Portable JSON formats — Personas and handoffs are portable and tool-agnostic
4. Open standards — .vstate.json and .vpersona.json are human-readable and shareable
5. MCP accessibility — Any connected AI tool can read and write to the shared data layer
6. Privacy by architecture — No external servers store any user data

Doramagic Pitfall Log

Found 13 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

1. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Cannot get NCCL test to run in docker with 2 x 6000 Pro connected x8 to AM4 CPU nvidia-smi topo -m is showing the both GPU as PHB (i.e. via CPU) connected as expected but I cannot get NCCL all\_reduce\_perf to run at all, it always hangs after starting up. It seems that vllm won't work with TP=2 until I can fix this.…
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: social_signal:reddit | ssig_95e79adcac9e42dcb6f9d43a46c10fd7 | https://www.reddit.com/r/LocalLLaMA/comments/1tkmh89/cannot_get_nccl_test_to_run_in_docker_with_2_x/

2. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: marx: review GitHub PRs with multiple agents, post a merged review 28 Jan 2026 · Written in Python, installable via uv. Feedback welcome. What else would you want from a multi-agent review tool? GitHub: https://github.com/ ...
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: social_signal:reddit | ssig_9423afda27ed41728b1d7813f2facca0 | https://www.reddit.com/r/ClaudeAI/comments/1qpfzjz/marx_review_github_prs_with_multiple_agents_post/

3. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | art_182ef5a2101a4d1487a4f06738b48342 | https://github.com/Vektor-Memory/Via#readme

4. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | art_182ef5a2101a4d1487a4f06738b48342 | https://github.com/Vektor-Memory/Via#readme

5. Runtime risk: Runtime risk requires verification

• Severity: medium
• Finding: Claude Sharing Option Hi! I want to set up for both me and my assistant, but Claude Teams has a 5-user minimum. What's the best workaround? What we need - shared projects with uploaded files, voice/style guides, Asana integration, Workarounds via project sharing or export/import Two separate Claude Pro accounts, what…
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: social_signal:reddit | ssig_a4b5801eee4b44908731af66e31f7599 | https://www.reddit.com/r/ClaudeAI/comments/1tkex6y/claude_sharing_option/

6. Runtime risk: Runtime risk requires verification

• Severity: medium
• Finding: MCP for JUST Writing Github issues? : r/ClaudeAI - Reddit 8 Jul 2025 · r/ClaudeAI - Built an MCP server that turns Claude Code into a full agent ... Best note-taking tool for use with Claude Code via MCP? (PM ...
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: social_signal:reddit | ssig_7523d654c76a4f45ab12bcde212d9d07 | https://www.reddit.com/r/ClaudeAI/comments/1lujlfq/mcp_for_just_writing_github_issues/

7. Runtime risk: Runtime risk requires verification

• Severity: medium
• Finding: [Bug]: RayExecutorV2 multi-node DP hangs on shm_broadcast — cross-node ranks can't share single-host shared memory ## Summary RayExecutorV2 (introduced via PR #36836, "[Feat][Executor] Introduce RayExecutorV2") inherits from MultiprocExecutor and uses shm_broadcast for inter-rank communication. shm_broadcast i…
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: social_signal:github | ssig_03e0c85cb7cd44dca332c0dd836a8409 | https://github.com/vllm-project/vllm/issues/43420

8. Runtime risk: Runtime risk requires verification

• Severity: medium
• Finding: why bothering with MCPs if I can call almost anything via CLI? - Reddit 26 Mar 2026 · yeah but again, WHY I need a tool like https://github.com/steipete/mcporter. ... mcp is worth it when the agent needs to pick which tool to call ...
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: social_signal:reddit | ssig_2c950dd9704e4fd2afc80b980e214b96 | https://www.reddit.com/r/LocalLLaMA/comments/1s41ltp/please_explain_why_bothering_with_mcps_if_i_can/

9. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | art_182ef5a2101a4d1487a4f06738b48342 | https://github.com/Vektor-Memory/Via#readme

10. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | art_182ef5a2101a4d1487a4f06738b48342 | https://github.com/Vektor-Memory/Via#readme

11. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | art_182ef5a2101a4d1487a4f06738b48342 | https://github.com/Vektor-Memory/Via#readme

12. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | art_182ef5a2101a4d1487a4f06738b48342 | https://github.com/Vektor-Memory/Via#readme

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using Via with real data or production workflows.

• [[Bug]: RayExecutorV2 multi-node DP hangs on shm_broadcast — cross-node r](https://github.com/vllm-project/vllm/issues/43420) - github / github_issues_search
• why bothering with MCPs if I can call almost anything via CLI? - Reddit - reddit / searxng_indexed
• Built a deep research engine that runs thousands of local agents via Oll - reddit / searxng_indexed
• A MCP universal integration layer Cli tool. It connects to other AI ... - reddit / searxng_indexed
• Cannot get NCCL test to run in docker with 2 x 6000 Pro connected x8 to - reddit / reddit_public_json
• Claude Sharing Option - reddit / reddit_public_json
• MCP for JUST Writing Github issues? : r/ClaudeAI - Reddit - reddit / searxng_indexed
• I built an open source UI framework that Claude can control through MCP - reddit / searxng_indexed
• marx: review GitHub PRs with multiple agents, post a merged review - reddit / searxng_indexed
• Github ‍ : Open-source AI Agent workflow builder. - x / searxng_indexed
• A coding agent session manager that manages itself via its own MCP - reddit / searxng_indexed
• Github ‍ : Open-source AI Agent workflow builder. - x / searxng_indexed