# https://github.com/Vektor-Memory/Via Project Manual
Generated at: 2026-06-02 10:59:14 UTC
## Table of Contents
- [Introduction to Via](#introduction)
- [Quick Start Guide](#quickstart)
- [System Architecture](#architecture)
- [AI Tool Connectors](#connectors)
- [Memory System](#memory-system)
- [AI Tool Comparison (via diff)](#diff-comparison)
- [File Conversion Pipeline](#file-conversion)
- [Task and Workflow Management](#task-management)
- [MCP Server Integration](#mcp-server)
- [Data Storage and Formats](#data-storage)
## Introduction to Via
### Related Pages
Related topics: [System Architecture](#architecture), [Quick Start Guide](#quickstart), [MCP Server Integration](#mcp-server)
Related Source Files
The following source files were used to generate this page:
- [README.md](https://github.com/Vektor-Memory/Via/blob/main/README.md)
- [SPEC.md](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
- [CHANGELOG.md](https://github.com/Vektor-Memory/Via/blob/main/CHANGELOG.md)
- [package.json](https://github.com/Vektor-Memory/Via/blob/main/package.json)
- [SECURITY.md](https://github.com/Vektor-Memory/Via/blob/main/SECURITY.md)
# 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 hello@vektormemory.com. [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
```mermaid
graph TD
subgraph "AI Tools"
Claude[Claude Code]
Cursor[Cursor]
Windsurf[Windsurf]
ChatGPT[ChatGPT]
end
subgraph "Via Core"
CLI[CLI Interface
via.mjs]
Commands[Commands Module
commands/*.mjs]
Utils[Utils Module
utils/*.mjs]
DB[(SQLite
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]()]
| Directory | Purpose |
|-----------|---------|
| `connectors/` | Tool-specific adapters (Claude, Cursor, Windsurf, ChatGPT, LangChain, Slipstream) |
| `commands/` | CLI command implementations (context, handoff, task, persona, spend, scaffold, watch, audit, sync, ingest, route, status) |
| `utils/` | Shared utilities (db.mjs, config.mjs, format.mjs, detect.mjs) |
### 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]()]
```bash
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]()]
```bash
via task add "refactor auth module" --high
via task
via task done
via task start
```
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]()]
```bash
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]()]
```bash
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]()]
```bash
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
```bash
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]()]
| MCP Tool | Description |
|----------|-------------|
| `via_task_list` | List open tasks |
| `via_task_add` | Add a task |
| `via_task_done` | Mark task done |
| `via_memory_add` | Store a fact |
| `via_memory_search` | Search stored facts (relationship-aware) |
| `via_log` | Log a decision or event |
| `via_context` | Pull formatted memory context |
| `via_status` | Ecosystem health check |
### Claude Desktop Configuration
```json
{
"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]()]
```bash
npx via --help
```
### Initial Setup
```bash
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]()]
| Preset | Use Case |
|--------|----------|
| `solo-dev` | Single developer workflow |
| `startup-team` | Small team collaboration |
| `enterprise-audit` | Compliance-focused tracking |
| `research` | Research-oriented projects |
## 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]()]
```json
{
"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]()]
```mermaid
graph TD
subgraph "Vektor Ecosystem"
Vex[Vex
Vector Exchange
Migrate memory between vector stores]
Via[Via
Universal Integration Layer
Route context across AI tools]
Slipstream[Slipstream
Intelligence Engine
Graph memory, vector search]
end
Via --> Vex
Via --> Slipstream
```
| Tool | Purpose | Function |
|------|---------|----------|
| Vex | Vector Exchange | Migrate agent memory between vector stores |
| Via | Route, path, through | Route context and execution across all AI tools |
| Slipstream | Intelligence engine | Graph memory, vector search, multimodal |
### 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]()]
| Feature | Via (Local) | Slipstream (Upgrade) |
|---------|-------------|----------------------|
| Memory | Chunked keyword | Vector embeddings |
| Task Board | Flat task list | Tasks linked to memory graph |
| Audit | Flat log | Causal decision graph |
| Team Sharing | Local only | Shared namespace |
| Search | Keyword only | BM25 + semantic dual-channel recall |
## 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 hello@vektormemory.com 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]()]
| Connector | Description | Status |
|-----------|-------------|--------|
| Claude | Claude Code connector | Active |
| Cursor | Cursor connector | Active |
| Windsurf | Windsurf connector | Active |
| ChatGPT | ChatGPT connector | Active |
| LangChain | LangChain connector | Active |
| Slipstream | Slipstream upgrade bridge | Active |
### 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]()]
| Version | Features |
|---------|----------|
| v0.2 (current) | `via init`, `via memory`, `via task`, `via log`, `via ask`, `via diff`, relationship-aware codebase indexing with symbols and import graph in SQLite, Claude Code session auto-capture, MCP server with 8 tools, Claude Desktop/Cursor/Windsurf support |
| v0.3 (coming) | Import edge traversal on Windows path fix, `via memory search` semantic upgrade via Slipstream, team-shared task board, `via diff --live` real-time comparison |
## 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 hello@vektormemory.com. [Source: [package.json]()]
Funding is categorized as "other" with additional information available at https://vektormemory.com/downloads. [Source: [package.json]()]
## Getting Started Flow
```mermaid
graph LR
A[Install via
npx via] --> B[Initialize
via init]
B --> C{Detect
AI Tools}
C -->|Claude| D[Configure
Claude Desktop MCP]
C -->|Cursor| E[Create
.cursor/rules]
C -->|Windsurf| F[Setup
Windsurf Config]
D --> G[Ready to Use]
E --> G
F --> G
G --> H[via serve
Start MCP Server]
---
## Quick Start Guide
### Related Pages
Related topics: [Introduction to Via](#introduction), [MCP Server Integration](#mcp-server)
Related Source Files
The following source files were used to generate this page:
- [package.json](https://github.com/Vektor-Memory/Via/blob/main/package.json)
- [README.md](https://github.com/Vektor-Memory/Via/blob/main/README.md)
- [SPEC.md](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
- [CHANGELOG.md](https://github.com/Vektor-Memory/Via/blob/main/CHANGELOG.md)
- [via.mjs](https://github.com/Vektor-Memory/Via/blob/main/via.mjs)
- [lib/config.mjs](https://github.com/Vektor-Memory/Via/blob/main/lib/config.mjs)
- [commands/init.mjs](https://github.com/Vektor-Memory/Via/blob/main/commands/init.mjs)
- [commands/serve.mjs](https://github.com/Vektor-Memory/Via/blob/main/commands/serve.mjs)
# 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
| Requirement | Version | Notes |
|-------------|---------|-------|
| Node.js | >= 18 | Native fetch API required |
| npm | Any recent version | For global installation |
| AI Tools | Claude Code, Cursor, Windsurf, or ChatGPT | At least one required |
Source: [package.json:29](https://github.com/Vektor-Memory/Via/blob/main/package.json)
## Installation
Via supports three installation methods. Choose the option that fits your workflow.
### Option 1: Zero-Install (Recommended for Tryouts)
```bash
npx via
```
No installation required. Downloads and runs the latest version on each invocation.
### Option 2: Global npm Install
```bash
npm install -g @vektor/via
```
This installs the `via` command globally and enables tab completion.
### Option 3: Project-Local Install
```bash
npm install @vektor/via
```
Useful for team projects where all developers should use the same Via version.
Source: [README.md:35-45](https://github.com/Vektor-Memory/Via/blob/main/README.md)
## Initial Setup with `via init`
The `init` command wires Via into every detected AI tool in a single command.
```bash
via init
```
### What `via init` Does
```mermaid
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`:
```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`:
```json
{
"project": "./my-project",
"slipstream": false,
"presets": ["solo-dev"]
}
```
Source: [SPEC.md:5.5](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md), [commands/init.mjs](https://github.com/Vektor-Memory/Via/blob/main/commands/init.mjs)
## Core Commands Reference
After installation, these are the primary commands you'll use daily.
| Command | Purpose |
|---------|---------|
| `via memory` | Relationship-aware code indexing |
| `via task` | Shared persistent task board |
| `via log` | Unified activity and decision logging |
| `via ask` | Route questions to the right AI tool |
| `via diff` | Compare AI tool responses |
| `via handoff` | Export/import working state between tools |
| `via serve` | Run Via as an MCP server |
| `via status` | Ecosystem health dashboard |
Source: [CHANGELOG.md:8-18](https://github.com/Vektor-Memory/Via/blob/main/CHANGELOG.md)
## Setting Up the MCP Server
The MCP server enables Claude Desktop, Cursor, and Windsurf to call Via tools natively.
### Start the MCP Server
```bash
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`):
```json
{
"mcpServers": {
"via": {
"command": "via",
"args": ["serve"]
}
}
}
```
### Available MCP Tools
When running as an MCP server, the following tools become available:
| MCP Tool | Function |
|----------|----------|
| `via_task_list` | List open tasks |
| `via_task_add` | Add a new task |
| `via_task_done` | Mark a task complete |
| `via_memory_add` | Store a fact or file reference |
| `via_memory_search` | Search stored facts with relationships |
| `via_log` | Log a decision or event |
| `via_context` | Pull formatted memory context |
| `via_status` | Check ecosystem health |
Source: [commands/serve.mjs](https://github.com/Vektor-Memory/Via/blob/main/commands/serve.mjs), [README.md:95-115](https://github.com/Vektor-Memory/Via/blob/main/README.md)
## Quick Workflows
### Workflow 1: First-Time Project Setup
```bash
# 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
```bash
# 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
```bash
# 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](https://github.com/Vektor-Memory/Via/blob/main/README.md)
## 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](https://github.com/Vektor-Memory/Via/blob/main/README.md)
## Verify Installation
Run the status command to confirm everything is connected:
```bash
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](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
## Next Steps
| Goal | Command |
|------|---------|
| Learn about memory indexing | `via memory --help` |
| Set up task tracking | `via task --help` |
| Track AI costs | `via spend --help` |
| Configure personas | `via persona --help` |
| Upgrade to Slipstream | `via upgrade` |
## Troubleshooting
### Tool Not Detected
```bash
# 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
```bash
# 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:
```bash
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](https://github.com/Vektor-Memory/Via/blob/main/CHANGELOG.md)
## Community and Support
| Resource | Link |
|----------|------|
| GitHub Issues | [github.com/Vektor-Memory/Via/issues](https://github.com/Vektor-Memory/Via/issues) |
| Security Issues | Email hello@vektormemory.com |
| Documentation | [vektormemory.com](https://vektormemory.com) |
| Slipstream (Upgrade) | [vektormemory.com/downloads](https://vektormemory.com/downloads) |
> **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](https://github.com/Vektor-Memory/Via/blob/main/SECURITY.md)
---
## System Architecture
### Related Pages
Related topics: [Introduction to Via](#introduction), [AI Tool Connectors](#connectors), [Data Storage and Formats](#data-storage)
Related Source Files
The following source files were used to generate this page:
- [via.mjs](https://github.com/Vektor-Memory/Via/blob/main/via.mjs)
- [utils/db.mjs](https://github.com/Vektor-Memory/Via/blob/main/utils/db.mjs)
- [utils/config.mjs](https://github.com/Vektor-Memory/Via/blob/main/utils/config.mjs)
- [utils/detect.mjs](https://github.com/Vektor-Memory/Via/blob/main/utils/detect.mjs)
- [utils/format.mjs](https://github.com/Vektor-Memory/Via/blob/main/utils/format.mjs)
- [SPEC.md](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
- [README.md](https://github.com/Vektor-Memory/Via/blob/main/README.md)
- [CHANGELOG.md](https://github.com/Vektor-Memory/Via/blob/main/CHANGELOG.md)
- [package.json](https://github.com/Vektor-Memory/Via/blob/main/package.json)
# 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](https://github.com/Vektor-Memory/Via/blob/main/README.md)
---
## High-Level Architecture
```mermaid
graph TD
subgraph "User Interface Layer"
CLI[CLI Commands
via.mjs]
MCP[MCP Server
via serve]
end
subgraph "Core Engine"
CMDS[Command Handlers]
DB[(SQLite
tasks.db
audit.db)]
CFG[Config Manager]
end
subgraph "Tool Connectors"
CLAUDE[Claude Connector]
CURSOR[Cursor Connector]
WINDSURF[Windsurf Connector]
CHATGPT[ChatGPT Connector]
end
subgraph "Utilities"
DETECT[Tool Detection]
FORMAT[Output Formatting]
end
CLI --> CMDS
MCP --> CMDS
CMDS --> DB
CMDS --> CFG
CMDS --> DETECT
CMDS --> FORMAT
CFG --> DETECT
DETECT --> CLAUDE
DETECT --> CURSOR
DETECT --> WINDSURF
DETECT --> CHATGPT
```
---
## Module Structure
### Directory Layout
```
via/
├── via.mjs # CLI entry point
├── utils/
│ ├── db.mjs # SQLite database operations
│ ├── config.mjs # Configuration reader/writer
│ ├── format.mjs # Output formatting (table, json, plain)
│ └── detect.mjs # Detect installed AI tools
├── connectors/ # Tool-specific adapters
├── commands/ # Command implementations
└── package.json
```
**Source:** [SPEC.md](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
### Core Modules
| Module | Purpose | Key Responsibilities |
|--------|---------|---------------------|
| `via.mjs` | CLI entry point | Command routing, argument parsing, main execution loop |
| `utils/db.mjs` | Database abstraction | SQLite initialization, CRUD operations, schema management |
| `utils/config.mjs` | Configuration management | Read/write `~/.via/config.json`, project-level config |
| `utils/detect.mjs` | Tool detection | Identify installed AI tools and their capabilities |
| `utils/format.mjs` | Output formatting | Table rendering, JSON output, plain text formatting |
**Source:** [package.json](https://github.com/Vektor-Memory/Via/blob/main/package.json), [SPEC.md](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
---
## Data Architecture
### Local Storage Directory
All Via data resides in `~/.via/`, ensuring user data never leaves the local machine:
```
~/.via/
├── config.json # User preferences, connected tools, API keys
├── tasks.db # SQLite: task board persistence
├── audit.db # SQLite: compliance/decision log
├── personas/ # Named AI persona definitions (.vpersona.json)
├── spend/ # Usage logs per tool per day
└── handoffs/ # Session state exports (.vstate.json)
```
**Source:** [SPEC.md](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
### Database Schema
#### Tasks Database
The task board uses SQLite with the following schema:
| Field | Type | Description |
|-------|------|-------------|
| id | INTEGER PRIMARY KEY | Auto-incrementing task identifier |
| title | TEXT | Task description |
| status | TEXT | One of: open, in-progress, done, blocked |
| tool | TEXT | AI tool that created/modified the task |
| persona | TEXT | Associated persona name |
| created_at | DATETIME | Creation timestamp |
| updated_at | DATETIME | Last modification timestamp |
| notes | TEXT | Additional context or comments |
#### Audit Database
Append-only compliance log structure:
| Field | Type | Description |
|-------|------|-------------|
| id | INTEGER PRIMARY KEY | Log entry identifier |
| tool | TEXT | Source AI tool |
| timestamp | DATETIME | When the decision was made |
| decision | TEXT | The logged decision or event |
| rationale | TEXT | Supporting context or justification |
**Source:** [SPEC.md - Section 6.3](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md), [SPEC.md - Section 6.8](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
---
## Command Architecture
### Command Hierarchy
Via implements 16 primary commands organized by domain:
```mermaid
graph TD
subgraph "Context Commands"
MEM[via memory] --> M_ADD[add]
MEM --> M_SEARCH[search]
MEM --> M_GRAPH[graph]
MEM --> M_LIST[list]
end
subgraph "Task Commands"
TASK[via task] --> T_ADD[add]
TASK --> T_LIST[list]
TASK --> T_DONE[done]
TASK --> T_START[start]
TASK --> T_UPDATE[update]
TASK --> T_DELETE[delete]
end
subgraph "Session Commands"
HAND[via handoff]
DIFF[via diff]
LOG[via log]
end
subgraph "Tool Commands"
ASK[via ask]
INIT[via init]
SCAFFOLD[via scaffold]
end
subgraph "Server Commands"
SERVE[via serve]
WATCH[via watch]
end
subgraph "Meta Commands"
STATUS[via status]
AUDIT[via audit]
SPEND[via spend]
INGEST[via ingest]
ROUTE[via route]
PERSONA[via persona]
SYNC[via sync]
UPGRADE[via upgrade]
end
```
### Command Execution Flow
```mermaid
sequenceDiagram
participant User
participant CLI as via.mjs
participant Config as config.mjs
participant DB as db.mjs
participant Format as format.mjs
User->>CLI: via
CLI->>CLI: Parse arguments
CLI->>Config: Load user config
alt Data command
CLI->>DB: Query/Update SQLite
DB-->>CLI: Results
end
CLI->>Format: Format output
Format-->>CLI: Formatted response
CLI-->>User: Display result
```
**Source:** [via.mjs](https://github.com/Vektor-Memory/Via/blob/main/via.mjs), [SPEC.md - Section 6](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
---
## MCP Server Architecture
Via can operate as an MCP (Model Context Protocol) server, exposing its functionality to MCP-compatible clients:
### Server Modes
| Mode | Transport | Use Case |
|------|-----------|----------|
| stdio | Standard input/output | Claude Desktop, Cursor |
| HTTP+SSE | HTTP + Server-Sent Events | Remote clients, web integrations |
**Source:** [README.md](https://github.com/Vektor-Memory/Via/blob/main/README.md)
### MCP Tool Interface
When running as an MCP server, the following tools are exposed:
| MCP Tool | Functionality |
|----------|---------------|
| `via_task_list` | List all open tasks |
| `via_task_add` | Create a new task |
| `via_task_done` | Mark a task as complete |
| `via_memory_add` | Store a fact or code snippet |
| `via_memory_search` | Search stored facts with relationship awareness |
| `via_log` | Log a decision or event |
| `via_context` | Retrieve formatted memory context |
| `via_status` | Check ecosystem health |
**Source:** [README.md](https://github.com/Vektor-Memory/Via/blob/main/README.md), [SPEC.md - Section 7](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
### MCP Configuration Example
```json
{
"mcpServers": {
"via": {
"command": "via",
"args": ["serve"]
}
}
}
```
Or via the `via init` command which auto-writes this configuration.
---
## Tool Integration Architecture
### Connector Pattern
Each AI tool has a dedicated connector that handles tool-specific interactions:
```mermaid
graph LR
subgraph "Via Core"
CORE[Command Handler]
STATE[(SQLite)]
end
subgraph "Connectors"
CLAUDE[Claude Connector
~/.claude/projects/*.jsonl]
CURSOR[Cursor Connector
~/.cursor/usage/*.jsonl]
WINDSURF[Windsurf Connector]
end
CORE --> CLAUDE
CORE --> CURSOR
CORE --> WINDSURF
CLAUDE --> STATE
CURSOR --> STATE
WINDSURF --> STATE
```
### Connector Responsibilities
| Connector | Data Source | Capabilities |
|------------|-------------|--------------|
| Claude | `~/.claude/projects/*.jsonl` | Session capture, decision logging, usage tracking |
| Cursor | `~/.cursor/usage/*.jsonl` | Usage logging, context retrieval |
| Windsurf | Local config detection | Tool status, configuration |
| ChatGPT | API log directory | Usage tracking |
**Source:** [SPEC.md - Section 6.5](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
---
## Configuration Architecture
### Configuration Hierarchy
Via uses a layered configuration system:
1. **Global config** (`~/.via/config.json`) — User preferences, connected tools
2. **Project config** (`via.config.json`) — Project-specific settings
3. **Environment variables** — Runtime overrides
4. **CLI flags** — Command-specific overrides
### Config Schema
```typescript
interface ViaConfig {
version: string;
tools: {
claude: { enabled: boolean; path?: string; };
cursor: { enabled: boolean; path?: string; };
windsurf: { enabled: boolean; path?: string; };
chatgpt: { enabled: boolean; apiKey?: string; };
};
slipstream?: {
endpoint: string;
apiKey: string;
};
preferences: {
defaultOutput: "table" | "json" | "plain";
autoSync: boolean;
notifications: boolean;
};
}
```
**Source:** [utils/config.mjs](https://github.com/Vektor-Memory/Via/blob/main/utils/config.mjs), [SPEC.md - Section 5](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
---
## Memory Architecture
### Relationship-Aware Code Indexing
Via's memory system goes beyond simple keyword storage by maintaining import relationships:
```mermaid
graph TD
A[auth.js] -->|imports| B[config.js]
A -->|imports| C[token.js]
D[server.js] -->|imports| A
E[middleware.js] -->|imports| A
F[routes.js] -->|imports| A
subgraph "Search: auth"
Q{Query: auth}
Q -->|Direct| A
Q -->|Direct| B
Q -->|Related via imports| D
Q -->|Related via imports| E
Q -->|Related via imports| F
end
```
### Supported Languages
The memory system extracts symbols and import edges from:
- JavaScript (.js, .mjs, .cjs)
- TypeScript (.ts, .tsx)
- Python (.py)
- Go (.go)
- Rust (.rs)
**Source:** [README.md](https://github.com/Vektor-Memory/Via/blob/main/README.md), [SPEC.md - Section 6.1](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
---
## Session Handoff Format
### `.vstate.json` Schema
When exporting session state for tool switching:
```json
{
"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?"
],
"decisions": [
{
"at": "2026-05-10T11:30:00Z",
"decision": "Use JWT with 1h expiry",
"tool": "cursor"
}
]
}
```
**Source:** [SPEC.md - Section 6.2](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
---
## Design Principles
### Architecture Constraints
| Principle | Implementation | Benefit |
|-----------|----------------|---------|
| Local-first | SQLite storage in `~/.via/` | Privacy, offline capability |
| No embeddings | Symbol + import graph only | Fast indexing, minimal dependencies |
| ESM-native | All connectors use top-level imports | Node 18+ compatibility |
| Native fetch | No `node-fetch` dependency | Reduced bundle size |
| Open formats | `.vstate.json`, `.vpersona.json` | Interoperability |
**Source:** [CHANGELOG.md](https://github.com/Vektor-Memory/Via/blob/main/CHANGELOG.md), [SPEC.md - Section 5](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
### Dependency Minimalism
Via requires only one runtime dependency:
```json
{
"dependencies": {
"sql.js": "^1.14.1"
}
}
```
Node.js version requirement: `>=18` (native ESM and fetch support).
**Source:** [package.json](https://github.com/Vektor-Memory/Via/blob/main/package.json)
---
## Vektor Ecosystem Integration
Via is part of a broader toolkit ecosystem:
| Product | Function | Architecture Role |
|---------|----------|-------------------|
| **Vex** | Vector memory portability | Migrate memory between vector stores |
| **Via** | Context routing | Universal integration layer |
| **Slipstream** | Intelligence engine | Graph memory, vector search, multimodal |
### Slipstream Upgrade Path
Local SQLite functionality can be enhanced by connecting to Slipstream:
| Feature | Local (SQLite) | Slipstream |
|---------|---------------|------------|
| Memory search | Keyword only | Semantic + BM25 dual-channel |
| Task linking | Flat list | Causal graph connections |
| Audit | Append-only log | Decision graph with memory links |
| Team sharing | Local only | Shared namespace |
**Source:** [README.md](https://github.com/Vektor-Memory/Via/blob/main/README.md), [SPEC.md - Section 8](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
---
## Security Architecture
### Data Privacy
Via maintains strict data locality:
- All data stored in `~/.via/` only
- No external API calls for indexing or storage
- Slipstream connection is optional and user-controlled
**Source:** [SECURITY.md](https://github.com/Vektor-Memory/Via/blob/main/SECURITY.md)
---
## Community Considerations
Based on community discussions, several architecture patterns are notable:
1. **MCP Universal Integration**: Via's MCP server implementation is highlighted as having features not found in other tools, particularly the ability to connect multiple AI tools (Qwen, Claude Code, Codex) through a unified interface. Source: [Reddit r/LocalLLaMA](https://www.reddit.com/r/LocalLLaMA/comments/1t9kom7/)
2. **Self-Managing Agent**: Via's architecture supports the pattern of a coding agent managing itself via its own MCP, enabling workflows where agents can return to PRs ready for merge. Source: [Reddit r/ClaudeAI](https://www.reddit.com/r/ClaudeAI/comments/1rtiqne/)
3. **Tool Selection via MCP**: The MCP abstraction is valuable when agents need to dynamically select which tool to call, rather than direct CLI invocation. Via's architecture supports this through its standardized tool interface. Source: [Reddit r/LocalLLaMA](https://www.reddit.com/r/LocalLLaMA/comments/1s41ltp/)
---
## AI Tool Connectors
### Related Pages
Related topics: [System Architecture](#architecture), [MCP Server Integration](#mcp-server), [AI Tool Comparison (via diff)](#diff-comparison)
Related Source Files
The following source files were used to generate this page:
- [SPEC.md](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md) — architectural overview, repository structure, and connector placement
- [README.md](https://github.com/Vektor-Memory/Via/blob/main/README.md) — usage patterns and supported tools
- [CHANGELOG.md](https://github.com/Vektor-Memory/Via/blob/main/CHANGELOG.md) — connector implementation history and fixes
- [package.json](https://github.com/Vektor-Memory/Via/blob/main/package.json) — project metadata and dependencies
- [SECURITY.md](https://github.com/Vektor-Memory/Via/blob/main/SECURITY.md) — security and data storage policies
- [connectors/claude.mjs](https://github.com/Vektor-Memory/Via/blob/main/connectors/claude.mjs) — Claude Code connector module
- [connectors/cursor.mjs](https://github.com/Vektor-Memory/Via/blob/main/connectors/cursor.mjs) — Cursor connector module
- [connectors/windsurf.mjs](https://github.com/Vektor-Memory/Via/blob/main/connectors/windsurf.mjs) — Windsurf connector module
- [connectors/chatgpt.mjs](https://github.com/Vektor-Memory/Via/blob/main/connectors/chatgpt.mjs) — ChatGPT connector module
- [connectors/langchain.mjs](https://github.com/Vektor-Memory/Via/blob/main/connectors/langchain.mjs) — LangChain connector module
- [connectors/slipstream.mjs](https://github.com/Vektor-Memory/Via/blob/main/connectors/slipstream.mjs) — Slipstream upgrade bridge module
# 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](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
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](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
## 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](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
### Design Pattern
Each connector follows a consistent pattern:
| Responsibility | Description |
|---|---|
| **Detection** | Identify if the tool is installed and accessible |
| **Session reading** | Parse tool-specific usage logs and session files |
| **Context formatting** | Format output for tool-specific context injection |
| **State handoff** | Export/import working state in tool-compatible format |
Source: [SPEC.md - Design Principles](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
### Connector Execution Flow
```mermaid
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](https://github.com/Vektor-Memory/Via/blob/main/README.md)
## 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](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
### 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](https://github.com/Vektor-Memory/Via/blob/main/CHANGELOG.md)
**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](https://github.com/Vektor-Memory/Via/blob/main/README.md)
### 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](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
### 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](https://github.com/Vektor-Memory/Via/blob/main/README.md)
### 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](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
**Capabilities when Slipstream is active:**
| Feature | Via (free) | Via + Slipstream |
|---|---|---|
| Memory search | SQLite FTS | BM25 + semantic + graph |
| Context assembly | Keyword match | Temporal relevance + graph |
| Task linking | Flat SQLite | Causally linked to memory graph |
| Ingest | Chunked keyword | Vector embeddings |
| Audit | Flat log | Causal decision graph |
| Team sharing | Local only | Shared namespace |
Source: [SPEC.md - Slipstream upgrade bridge](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
## 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](https://github.com/Vektor-Memory/Via/blob/main/CHANGELOG.md)
**Version requirement:**
```
Node.js >= 18
```
Source: [package.json - engines](https://github.com/Vektor-Memory/Via/blob/main/package.json)
## 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](https://github.com/Vektor-Memory/Via/blob/main/CHANGELOG.md)
## Tool Detection
Via uses `utils/detect.mjs` to identify which AI tools are installed on the system before attempting to use their connectors.
```mermaid
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](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
## 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](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
## 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](https://github.com/Vektor-Memory/Via/blob/main/SECURITY.md)
## 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](https://www.reddit.com/r/LocalLLaMA/comments/1t9kom7/a_mcp_universal_integration_layer_cli_tool_it/)
### 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](https://www.reddit.com/r/ClaudeAI/comments/1rtiqne/a_coding_agent_session_manager_that_manages/)
### 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](https://www.reddit.com/r/LocalLLaMA/comments/1s41ltp/please_explain_why_bothering_with_mcps_if_i_can/)
## 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](https://github.com/Vektor-Memory/Via/blob/main/README.md)
## See Also
- [Via CLI Commands](SPEC.md#6-commands) — Commands that utilize connectors
- [MCP Server Mode](SPEC.md#7-mcp-server-mode) — Via as an MCP server exposing connector tools
- [Slipstream Upgrade Bridge](SPEC.md#8-slipstream-upgrade-bridge) — Upgrade path for enhanced connector capabilities
- [Vektor Ecosystem](README.md#vektor-ecosystem) — Via, Vex, and Slipstream integration
---
## Memory System
### Related Pages
Related topics: [Data Storage and Formats](#data-storage), [System Architecture](#architecture), [Task and Workflow Management](#task-management)
Related Source Files
The following source files were used to generate this page:
- [commands/memory.mjs](https://github.com/Vektor-Memory/Via/blob/main/commands/memory.mjs)
- [commands/context.mjs](https://github.com/Vektor-Memory/Via/blob/main/commands/context.mjs)
- [commands/ingest.mjs](https://github.com/Vektor-Memory/Via/blob/main/commands/ingest.mjs)
- [utils/db.mjs](https://github.com/Vektor-Memory/Via/blob/main/utils/db.mjs)
- [SPEC.md](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
- [README.md](https://github.com/Vektor-Memory/Via/blob/main/README.md)
# 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:**
| Property | Local Mode | Slipstream Upgrade |
|----------|------------|-------------------|
| Storage | SQLite | SQLite + Vector DB |
| Search | Keyword/BM25 | Semantic embeddings |
| Relationships | Import graph traversal | Causal graph linking |
| Team sharing | Local only | Shared namespace |
| API calls | None | On-demand |
Source: [SPEC.md](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
## Architecture
The Memory System comprises three primary command modules that work together to provide comprehensive knowledge management:
```mermaid
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
| Component | File | Purpose |
|-----------|------|---------|
| Memory Commands | `commands/memory.mjs` | Store facts, index codebases, search |
| Ingest Pipeline | `commands/ingest.mjs` | Universal knowledge intake |
| Context Formatter | `commands/context.mjs` | Format memory for AI tools |
| Database Layer | `utils/db.mjs` | SQLite operations and schema |
Source: [commands/memory.mjs](https://github.com/Vektor-Memory/Via/blob/main/commands/memory.mjs), [utils/db.mjs](https://github.com/Vektor-Memory/Via/blob/main/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
```bash
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](https://github.com/Vektor-Memory/Via/blob/main/commands/memory.mjs)
### Listing Stored Facts
```bash
via memory list
```
This command displays all indexed files and stored facts with their timestamps and source information.
Source: [README.md](https://github.com/Vektor-Memory/Via/blob/main/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:
| Language | Extensions | Symbol Types |
|----------|------------|--------------|
| JavaScript | `.js`, `.mjs` | functions, classes, exports |
| TypeScript | `.ts`, `.tsx` | interfaces, types, exports |
| Python | `.py` | functions, classes, imports |
| Go | `.go` | functions, structs, imports |
| Rust | `.rs` | functions, structs, modules |
Source: [commands/memory.mjs](https://github.com/Vektor-Memory/Via/blob/main/commands/memory.mjs)
### Indexing a Codebase
```bash
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](https://github.com/Vektor-Memory/Via/blob/main/README.md)
### Import Graph Visualization
```bash
via memory graph
```
Displays the import relationships between files, showing how code is connected architecturally rather than just textually.
Source: [README.md](https://github.com/Vektor-Memory/Via/blob/main/README.md)
## Universal Knowledge Ingestion
The `via ingest` command provides a universal intake pipeline for external knowledge sources.
### Supported Sources
| Source Type | Method | Processing |
|-------------|--------|------------|
| URL | Plain HTTP fetch | HTML parsing, text extraction |
| File (txt, md) | Direct read | Chunking |
| File (PDF) | Poppler `pdftotext` | Text extraction, chunking |
| Directory | Recursive walk | Per-file processing, respects `.gitignore` |
Source: [SPEC.md](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
### Ingestion Pipeline
```mermaid
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
```bash
# 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](https://github.com/Vektor-Memory/Via/blob/main/commands/ingest.mjs), [SPEC.md](https://github.com/Vektor-Memory/Via/blob/main/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
| Tool | Format File | Context Injection |
|------|-------------|-------------------|
| Claude Code | `CLAUDE.md` block | Multi-turn conversation |
| Cursor | `.cursor/rules/*.mdc` | Project rules |
| Windsurf | Custom rules | Project context |
| ChatGPT | Session context | Prompt formatting |
Source: [commands/context.mjs](https://github.com/Vektor-Memory/Via/blob/main/commands/context.mjs)
### Output Format Example
```bash
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](https://github.com/Vektor-Memory/Via/blob/main/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
| Feature | Local Via | Via + Slipstream |
|---------|-----------|------------------|
| Fact storage | Keyword search | Vector embeddings |
| Codebase search | Import graph traversal | Semantic symbol search |
| Relationship linking | Static import edges | Causal decision graph |
| Team sharing | Local only | Shared namespace |
| Multimodal | Text only | Images, documents, audio |
Source: [SPEC.md](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
### Upgrade Command
```bash
npx via upgrade
```
This connects your local Via installation to Slipstream, enabling semantic search and team features.
Source: [CHANGELOG.md](https://github.com/Vektor-Memory/Via/blob/main/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
| MCP Tool | Function | Description |
|----------|----------|-------------|
| `via_memory_add` | Store a fact | Adds fact to SQLite database |
| `via_memory_search` | Search memory | Relationship-aware fact lookup |
| `via_context` | Format context | Pull formatted memory for tool |
Source: [README.md](https://github.com/Vektor-Memory/Via/blob/main/README.md)
### Configuration
Via's MCP server is configured automatically when you run:
```bash
via init
```
This writes the necessary MCP configuration to:
- Claude Desktop: `~/.claude/projects/*/mcp.json`
- Cursor: `.cursor/rules/`
Source: [README.md](https://github.com/Vektor-Memory/Via/blob/main/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)
| Table | Purpose |
|-------|---------|
| `facts` | Plain-text knowledge entries |
| `files` | Indexed source file metadata |
| `symbols` | Extracted functions, classes, exports |
| `imports` | Import relationship edges |
Source: [utils/db.mjs](https://github.com/Vektor-Memory/Via/blob/main/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](https://github.com/Vektor-Memory/Via/blob/main/SECURITY.md)
## Command Reference
### `via memory add`
Store a fact or index a codebase.
```bash
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.
```bash
via memory search "auth" # search + related files
```
### `via memory graph`
Display import relationships as a visual graph.
```bash
via memory graph # show import relationships
```
### `via memory list`
List all indexed files and stored facts.
```bash
via memory list # list indexed files + facts
```
### `via ingest`
Universal knowledge intake pipeline.
```bash
via ingest # ingest content
```
### `via context`
Format memory context for a specific AI tool.
```bash
via context "query" # pull formatted context
```
Source: [commands/memory.mjs](https://github.com/Vektor-Memory/Via/blob/main/commands/memory.mjs), [README.md](https://github.com/Vektor-Memory/Via/blob/main/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](https://github.com/Vektor-Memory/Via/blob/main/README.md)
---
*Part of the Vektor ecosystem: [Vex](https://github.com/Vektor-Memory/Vex) (memory portability) · [Via](https://github.com/Vektor-Memory/Via) (context routing) · [Slipstream](https://vektormemory.com) (intelligence engine)*
---
## AI Tool Comparison (via diff)
### Related Pages
Related topics: [AI Tool Connectors](#connectors)
Related Source Files
The following source files were used to generate this page:
- [README.md](https://github.com/Vektor-Memory/Via/blob/main/README.md)
- [README.html](https://github.com/Vektor-Memory/Via/blob/main/README.html)
- [SPEC.md](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
- [package.json](https://github.com/Vektor-Memory/Via/blob/main/package.json)
- [CHANGELOG.md](https://github.com/Vektor-Memory/Via/blob/main/CHANGELOG.md)
# 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](https://www.reddit.com/r/LocalLLaMA/comments/1t9kom7/a_mcp_universal_integration_layer_cli_tool_it/)
## Purpose and Scope
The comparison engine serves multiple use cases:
| Use Case | Description |
|----------|-------------|
| **Prompt Engineering** | Evaluate which phrasing produces better results across tools |
| **Tool Evaluation** | Compare Claude, Cursor, Codex, and other AI tools systematically |
| **Knowledge Synthesis** | Identify unique insights from each tool and merge them |
| **Consistency Checking** | Verify that different tools provide compatible recommendations |
| **Decision Support** | When tools disagree, identify the key terms driving the divergence |
Source: [README.md](https://github.com/Vektor-Memory/Via/blob/main/README.md)
## Architecture
### Data Flow
```mermaid
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](https://github.com/Vektor-Memory/Via/blob/main/README.md)
## Commands Reference
### Primary Commands
| Command | Description |
|---------|-------------|
| `via diff "prompt"` | Register a new comparison prompt |
| `via diff add ""` | Store a tool's response for the active comparison |
| `via diff show` | Display side-by-side comparison with analysis |
| `via diff list` | List all saved comparisons |
Source: [README.md](https://github.com/Vektor-Memory/Via/blob/main/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](https://github.com/Vektor-Memory/Via/blob/main/README.md)
## Usage Examples
### Basic Comparison Workflow
```bash
# 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](https://github.com/Vektor-Memory/Via/blob/main/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](https://github.com/Vektor-Memory/Via/blob/main/README.md)
### Listing Saved Comparisons
```bash
via diff list
```
Displays all previously saved comparisons for review and re-comparison.
Source: [README.md](https://github.com/Vektor-Memory/Via/blob/main/README.md)
## Output Components
### Display Elements
| Element | Description |
|---------|-------------|
| **Word Count** | Token/word count per tool response |
| **Similarity Score** | Percentage of word overlap between responses |
| **Side-by-Side View** | Aligned text comparison showing each tool's answer |
| **Unique Terms** | Vocabulary exclusive to each tool |
Source: [README.md](https://github.com/Vektor-Memory/Via/blob/main/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](https://github.com/Vektor-Memory/Via/blob/main/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:
```bash
via serve # stdio mode for Claude Desktop, Cursor
via serve --sse # HTTP+SSE mode for remote connections
```
Source: [README.md](https://github.com/Vektor-Memory/Via/blob/main/README.md)
## Roadmap
### v0.3 (Coming)
| Feature | Description |
|---------|-------------|
| `via diff --live` | Real-time comparison as tools respond |
Source: [README.md](https://github.com/Vektor-Memory/Via/blob/main/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
| Command | Relationship |
|---------|--------------|
| `via ask` | Route questions to specific tools before comparison |
| `via handoff` | Export comparison state between tools |
| `via memory` | Store insights discovered from comparisons |
Source: [README.md](https://github.com/Vektor-Memory/Via/blob/main/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](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
---
## File Conversion Pipeline
### Related Pages
Related topics: [Memory System](#memory-system), [Data Storage and Formats](#data-storage)
Related Source Files
The following source files were used to generate this page:
- [commands/convert.mjs](https://github.com/Vektor-Memory/Via/blob/main/commands/convert.mjs)
- [README.md](https://github.com/Vektor-Memory/Via/blob/main/README.md)
- [SPEC.md](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
- [CHANGELOG.md](https://github.com/Vektor-Memory/Via/blob/main/CHANGELOG.md)
- [package.json](https://github.com/Vektor-Memory/Via/blob/main/package.json)
# 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
| Attribute | Description |
|----------|-------------|
| **Processing** | 100% local — no uploads or API calls |
| **Integration** | Optional memory pipeline for converted content |
| **Tool Check** | Built-in validation of required external dependencies |
| **Format Discovery** | Comprehensive list of all supported conversions |
## Architecture
```mermaid
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
| Input | Output |
|-------|--------|
| png, jpg, webp, gif, bmp, tiff, ico, svg | png, jpg, webp, gif, bmp, tiff, ico, pdf |
Image conversion relies on ImageMagick for the heavy lifting.
### Audio
| Input | Output |
|-------|--------|
| mp3, wav, ogg, m4a, aac, flac, aiff, wma | mp3, wav, ogg, m4a, aac, flac, aiff |
Audio processing uses FFmpeg.
### Video
| Input | Output |
|-------|--------|
| mp4, mkv, mov, avi, webm, flv, wmv | mp4, mkv, mov, avi, webm, gif, mp3 |
Video conversion supports extraction of audio tracks (to mp3) and animation conversion (to gif).
### Documents
| Input | Output |
|-------|--------|
| md, rst, html, txt, tex, org, epub | md, html, txt, pdf, epub, docx, odt |
Document conversion uses Pandoc as the primary processor.
### Office Files
| Input | Output |
|-------|--------|
| docx, doc, odt, rtf, xlsx, pptx | pdf, txt, html, odt, docx |
Office document processing requires LibreOffice.
### PDF
| Input | Output |
|-------|--------|
| pdf | txt, md, html, docx |
PDF text extraction uses Poppler's pdftotext utility.
### Archives
| Input | Output |
|-------|--------|
| Any file or folder | zip, tar.gz, 7z |
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.
```bash
via convert --check
```
### Tool Matrix
| Tool | Purpose | Required For |
|------|---------|--------------|
| FFmpeg | Audio/video processing | Audio, video, gif extraction |
| ImageMagick | Image processing | All image format conversions |
| Pandoc | Document markup | md, rst, html, tex, org, epub |
| LibreOffice | Office documents | docx, doc, odt, rtf, xlsx, pptx |
| Poppler | PDF utilities | pdftotext for PDF text extraction |
| Zip | Archive creation | zip compression |
| 7-Zip | Archive creation | 7z compression |
## Command Reference
### Basic Conversion
```bash
via convert --to
```
Converts a single file to the specified format. The output is written to the current directory with the original filename and new extension.
**Example:**
```bash
via convert ./report.pdf --to md
# Output: ./report.md
```
### Conversion with Memory Ingestion
```bash
via convert --to --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:**
```bash
via convert ./report.pdf --to md --ingest
# Converts to markdown and stores in memory
```
### Tool Availability Check
```bash
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
```bash
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:
```mermaid
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`:
```json
{
"convert": {
"defaultOutputDir": ".",
"overwrite": false
}
}
```
## Troubleshooting
### Missing Tools
If `--check` reports missing tools, install them via your system package manager:
**macOS:**
```bash
brew install ffmpeg imagemagick pandoc libreoffice poppler p7zip
```
**Ubuntu/Debian:**
```bash
apt-get install ffmpeg imagemagick pandoc libreoffice poppler-utils p7zip-full
```
**Windows:**
Use chocolatey or scoop to install equivalent packages.
### Conversion Failures
| Error | Cause | Solution |
|-------|-------|----------|
| Unsupported format | Format pair not in matrix | Check `via convert --formats` |
| Tool not found | External dependency missing | Run `via convert --check` |
| Permission denied | Output directory not writable | Check directory permissions |
| Corrupt input | Source file damaged | Verify source file integrity |
## Workflow Examples
### Document Processing Pipeline
```bash
# 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
```bash
# 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:
| Command | Relationship |
|---------|--------------|
| `via memory` | Stores and retrieves converted content |
| `via ingest` | Universal intake for files, URLs, directories |
| `via context` | Formats memory content for AI tools |
| `via serve` | Exposes convert as MCP tool |
## 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](https://github.com/Vektor-Memory/Via/blob/main/README.md)
Source: [SPEC.md](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
Source: [CHANGELOG.md](https://github.com/Vektor-Memory/Via/blob/main/CHANGELOG.md)
---
## Task and Workflow Management
### Related Pages
Related topics: [Introduction to Via](#introduction), [MCP Server Integration](#mcp-server), [Data Storage and Formats](#data-storage)
Related Source Files
The following source files were used to generate this page:
- [SPEC.md](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
- [README.md](https://github.com/Vektor-Memory/Via/blob/main/README.md)
- [via.mjs](https://github.com/Vektor-Memory/Via/blob/main/via.mjs)
- [commands/task.mjs](https://github.com/Vektor-Memory/Via/blob/main/commands/task.mjs)
- [commands/log.mjs](https://github.com/Vektor-Memory/Via/blob/main/commands/log.mjs)
- [commands/handoff.mjs](https://github.com/Vektor-Memory/Via/blob/main/commands/handoff.mjs)
- [commands/ask.mjs](https://github.com/Vektor-Memory/Via/blob/main/commands/ask.mjs)
- [commands/diff.mjs](https://github.com/Vektor-Memory/Via/blob/main/commands/diff.mjs)
- [lib/db.mjs](https://github.com/Vektor-Memory/Via/blob/main/lib/db.mjs)
# 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:
| Command | Purpose | Data Storage |
|---------|---------|--------------|
| `via task` | Shared persistent task board | SQLite (`tasks.db`) |
| `via log` | Unified activity and decision logging | JSONL + SQLite |
| `via handoff` | Session state export/import | `.vstate.json` files |
| `via ask` | Task routing to appropriate AI tool | Configuration-based |
| `via diff` | Compare AI tool responses | SQLite |
This architecture ensures that work context persists regardless of which AI tool you're currently using. Source: [SPEC.md](https://github.com/Vektor-Memory/Via/blob/main/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](https://github.com/Vektor-Memory/Via/blob/main/commands/task.mjs)
#### Task Subcommands
| Subcommand | Description |
|------------|-------------|
| `add ` | Create a new task with optional priority |
| `list` | Display all tasks with status indicators |
| `update <id>` | Modify task details |
| `done <id>` | Mark task as completed |
| `start <id>` | Move task to in-progress status |
| `next` | Get the highest priority open task |
| `delete <id>` | Remove a task permanently |
#### Task Data Model
Each task in Via maintains the following fields:
```json
{
"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](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
#### Usage Examples
```bash
# 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:
| MCP Tool | Function |
|----------|----------|
| `via_task_list` | Retrieve all open tasks |
| `via_task_add` | Create a new task |
| `via_task_done` | Mark task completed |
| `via_task_start` | Begin task execution |
| `via_task_update` | Modify task properties |
| `via_task_delete` | Remove a task |
This enables AI tools like Claude Code, Cursor, and Windsurf to read and update the shared task board natively. Source: [README.md](https://github.com/Vektor-Memory/Via/blob/main/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](https://github.com/Vektor-Memory/Via/blob/main/commands/log.mjs)
#### Log Subcommands
| Subcommand | Description |
|------------|-------------|
| `via log "message"` | Record a decision or event |
| `--tool <name>` | Specify source tool (auto-detected if omitted) |
| `--scan` | One-shot capture of all Claude Code sessions |
| `--watch` | Live capture as sessions complete |
| `--today` | Show today's log entries |
| `search <query>` | Full-text search through logs |
### 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](https://github.com/Vektor-Memory/Via/blob/main/README.md)
```bash
# 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](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
```
┌─ 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](https://github.com/Vektor-Memory/Via/blob/main/commands/handoff.mjs)
#### Handoff Workflow
```mermaid
graph LR
A[Claude Code] -->|via handoff --export| B[.vstate.json]
B -->|via handoff --import| C[Cursor]
C -->|continues| D[Sprint Work]
```
#### Export Operations
```bash
# 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
```bash
# 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:
```json
{
"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](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
## 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](https://github.com/Vektor-Memory/Via/blob/main/commands/ask.mjs)
```bash
# 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:
| Task Characteristic | Recommended Tool |
|--------------------|--------------------|
| Long research tasks | Claude |
| Code completion tasks | Cursor |
| Cheap summarization | Lowest cost model |
| Specific tool preference | User-specified tool |
Future versions will incorporate ML routing based on spend/outcome history. Source: [SPEC.md:6.11](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
## 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](https://github.com/Vektor-Memory/Via/blob/main/commands/diff.mjs)
#### Diff Workflow
```mermaid
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
```bash
# 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:
| Feature | Via Local | Via + Slipstream |
|---------|-----------|------------------|
| Task storage | Flat SQLite list | Causally linked to memory graph |
| Search | Keyword match | Temporal relevance + graph |
| Cross-tool sync | Local only | Shared namespace |
| Decision tracking | Flat log | Causal decision graph |
Source: [SPEC.md:8](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
## 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](https://github.com/Vektor-Memory/Via/blob/main/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](https://www.reddit.com/r/ClaudeAI/comments/1rtiqne/a_coding_agent_session_manager_that_manages/)
- **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:**
```bash
# 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:**
```bash
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:
```bash
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
---
<a id='mcp-server'></a>
## MCP Server Integration
### Related Pages
Related topics: [Introduction to Via](#introduction), [AI Tool Connectors](#connectors), [Quick Start Guide](#quickstart)
<details>
<summary>Related Source Files</summary>
The following source files were used to generate this page:
- [SPEC.md](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
- [README.md](https://github.com/Vektor-Memory/Via/blob/main/README.md)
- [CHANGELOG.md](https://github.com/Vektor-Memory/Via/blob/main/CHANGELOG.md)
- [package.json](https://github.com/Vektor-Memory/Via/blob/main/package.json)
- [via.mjs](https://github.com/Vektor-Memory/Via/blob/main/via.mjs)
</details>
# 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:
| Mode | Command | Use Case | Transport |
|------|---------|----------|-----------|
| stdio | `via serve` | Claude Desktop, Cursor, local tools | Standard I/O |
| HTTP+SSE | `via serve --sse` | Remote connections, multi-machine setups | Server-Sent Events |
```mermaid
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
| Tool Name | Description | Parameters |
|-----------|-------------|------------|
| `via_task_list` | List all open tasks | None required |
| `via_task_add` | Add a new task | `title`, `status`, `priority` |
| `via_task_done` | Mark a task as complete | `id` |
| `via_memory_add` | Store a fact or piece of context | `content`, `tags` |
| `via_memory_search` | Search stored facts with relationship awareness | `query`, `limit` |
| `via_log` | Log a decision or event | `message`, `tool`, `category` |
| `via_context` | Pull formatted memory context | `query`, `format` |
| `via_status` | Ecosystem health check | None required |
**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`
```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:
```bash
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:
```javascript
// 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
```mermaid
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
```mermaid
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:
| Feature | Via Local | Via + Slipstream |
|---------|-----------|------------------|
| Memory search | SQLite FTS | BM25 + semantic + graph |
| Context assembly | Keyword match | Temporal relevance + graph |
| Ingest | Chunked keyword | Vector embeddings |
| Team sharing | Local only | Shared namespace |
**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
| Issue | Solution |
|-------|----------|
| MCP tools not appearing in Claude | Run `via init` to regenerate Claude Desktop config |
| SSE connection timeout | Check firewall settings; SSE requires port accessibility |
| SQLite lock errors | Ensure only one MCP server instance is running |
### Health Check
Run `via status` to verify MCP server connectivity and tool registration:
```bash
via status
```
Expected output includes MCP tool registration status and connected tool health indicators.
**Source:** [SPEC.md:6.12]()
## Version History
| Version | Change |
|---------|--------|
| 0.1.0 | Initial MCP server release with 8 tools (via serve) |
| 0.3.1 | Current stable version |
**Source:** [CHANGELOG.md](), [package.json:4]()
## See Also
- [Via Command Reference](README.md#commands) — Complete list of Via commands
- [Slipstream Integration](SPEC.md#8-slipstream-upgrade-bridge) — Upgrade path for enhanced memory
- [Vektor Ecosystem](README.md#vektor-ecosystem) — Related Vektor Memory products
---
<a id='data-storage'></a>
## Data Storage and Formats
### Related Pages
Related topics: [System Architecture](#architecture), [Memory System](#memory-system)
<details>
<summary>Related Source Files</summary>
The following source files were used to generate this page:
- [utils/db.mjs](https://github.com/Vektor-Memory/Via/blob/main/utils/db.mjs)
- [utils/config.mjs](https://github.com/Vektor-Memory/Via/blob/main/utils/config.mjs)
- [commands/audit.mjs](https://github.com/Vektor-Memory/Via/blob/main/commands/audit.mjs)
- [commands/spend.mjs](https://github.com/Vektor-Memory/Via/blob/main/commands/spend.mjs)
- [commands/task.mjs](https://github.com/Vektor-Memory/Via/blob/main/commands/task.mjs)
- [commands/persona.mjs](https://github.com/Vektor-Memory/Via/blob/main/commands/persona.mjs)
- [commands/handoff.mjs](https://github.com/Vektor-Memory/Via/blob/main/commands/handoff.mjs)
- [SPEC.md](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)
</details>
# 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:
```mermaid
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:
| Storage Type | Technology | Purpose | Accessibility |
|--------------|------------|---------|---------------|
| Relational Data | SQLite | Tasks, audit logs | Direct database queries |
| Configuration | JSON | User preferences, tool connections | Human-readable, version-controllable |
| Personas | JSON | Named agent personas | Portable, shareable |
| Spend Data | JSONL | Usage logs per tool | Append-only, analyzable |
| Session State | JSON | Cross-tool handoffs | Exportable, importable |
*Source: [SPEC.md](https://github.com/Vektor-Memory/Via/blob/main/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](https://github.com/Vektor-Memory/Via/blob/main/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.
```mermaid
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:**
| Column | Type | Description | Constraints |
|--------|------|-------------|-------------|
| id | TEXT | Unique task identifier | PRIMARY KEY |
| title | TEXT | Task description | NOT NULL |
| status | TEXT | open, in-progress, done, blocked | NOT NULL, DEFAULT 'open' |
| tool | TEXT | Associated AI tool | NULLABLE |
| persona | TEXT | Associated persona | NULLABLE |
| priority | TEXT | high, medium, low | NULLABLE |
| created_at | TEXT | ISO 8601 timestamp | NOT NULL |
| updated_at | TEXT | ISO 8601 timestamp | NOT NULL |
| notes | TEXT | Additional context | NULLABLE |
*Source: [commands/task.mjs](https://github.com/Vektor-Memory/Via/blob/main/commands/task.mjs)*
**Available Operations:**
```bash
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.
| Column | Type | Description | Constraints |
|--------|------|-------------|-------------|
| id | TEXT | Unique log entry ID | PRIMARY KEY |
| tool | TEXT | Source AI tool | NOT NULL |
| decision | TEXT | Decision description | NOT NULL |
| rationale | TEXT | Reasoning provided | NULLABLE |
| timestamp | TEXT | ISO 8601 timestamp | NOT NULL |
| metadata | TEXT | JSON metadata | NULLABLE |
*Source: [commands/audit.mjs](https://github.com/Vektor-Memory/Via/blob/main/commands/audit.mjs)*
**Export Formats:**
- `jsonl` — JSON Lines (newline-delimited JSON)
- `csv` — Comma-separated values
- `markdown` — Formatted markdown table
```bash
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.
```json
{
"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](https://github.com/Vektor-Memory/Via/blob/main/utils/config.mjs)*
### Project Configuration (via.config.json)
Project-level configuration stored in the repository root:
```json
{
"project": "my-app",
"preset": "startup-team",
"memory": {
"index_paths": ["./src", "./docs"],
"exclude": ["node_modules", ".git"]
},
"personas": ["developer", "reviewer"]
}
```
*Source: [SPEC.md](https://github.com/Vektor-Memory/Via/blob/main/SPEC.md)*
## Open Formats
### Session Handoff Format (.vstate.json)
The session handoff format enables transferring working state between AI tools and machines.
```json
{
"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](https://github.com/Vektor-Memory/Via/blob/main/commands/handoff.mjs)*
**Usage:**
```bash
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/`.
```json
{
"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](https://github.com/Vektor-Memory/Via/blob/main/commands/persona.mjs)*
**Persona Commands:**
```bash
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`:
```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`:
```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](https://github.com/Vektor-Memory/Via/blob/main/commands/spend.mjs)*
**Spend Commands:**
```bash
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
```mermaid
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:
```javascript
// 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](https://github.com/Vektor-Memory/Via/blob/main/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:
| Data Type | Storage Location | External Access |
|-----------|------------------|-----------------|
| Tasks | ~/.via/tasks.db | Via MCP tools only |
| Audit Log | ~/.via/audit.db | Via MCP tools only |
| Configuration | ~/.via/config.json | Via commands only |
| Personas | ~/.via/personas/ | Via commands, exportable |
| Spend Logs | ~/.via/spend/ | Via commands, read-only |
| Handoffs | ~/.via/handoffs/ | Via commands, portable |
All data remains local. No VEKTOR servers receive, store, or process any user data. This is enforced architecturally, not merely policy.
*Source: [SECURITY.md](https://github.com/Vektor-Memory/Via/blob/main/SECURITY.md)*
## Slipstream Upgrade Path
The local SQLite storage represents the "Slipstream ceiling" for Via's base tier:
| Feature | Local (SQLite) | Slipstream (Upgrade) |
|---------|----------------|----------------------|
| Task Storage | Keyword search only | Causal graph linking |
| Memory | Flat fact storage | Vector embeddings + semantic search |
| Audit Log | Flat search | Decision graph with temporal relevance |
| Multi-machine | Manual handoffs | Automatic sync via GitHub |
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](https://github.com/Vektor-Memory/Via/blob/main/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
---
<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->
---
## Pitfall Log
Project: Vektor-Memory/Via
Summary: 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
- Evidence strength: source_linked
- 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.
- Suggested 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
- Evidence strength: source_linked
- 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.
- Suggested 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
- Evidence strength: source_linked
- 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.
- Suggested 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
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested 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
- Evidence strength: source_linked
- 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.
- Suggested 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
- Evidence strength: source_linked
- 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.
- Suggested 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
- Evidence strength: source_linked
- 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.
- Suggested 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
- Evidence strength: source_linked
- 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.
- Suggested 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
- Evidence strength: source_linked
- 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.
- Suggested 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
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested 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
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested 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
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested 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
## 13. Maintenance risk - Maintenance risk requires verification
- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested 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
<!-- canonical_name: Vektor-Memory/Via; human_manual_source: deepwiki_human_wiki -->