Vault Axis (vaxis)

Persistent memory and GGAN coordinate engine for developers -- maintain a single Obsidian vault across all your projects. Each project becomes a cluster in the graph. Over time the vault becomes your full builder brain -- navigable by you and by AI editors.

Installation

npm install -g @varkos/vaxis

That's it. @varkos/vaxis is now available globally on your system.

Quick Start

# Navigate to any project and run:
vaxis init

That single command handles everything:

1. First-time setup (asks for your Obsidian vault path and developer name)
2. Scans your project
3. Generates interlinked vault notes
4. Creates a .code-workspace linking your project + vault
5. Writes AI rule files for GGAN navigation
6. Opens Obsidian to your project's index

Config is saved to ~/.vaxis/config.json.

Commands

| Command | Description | |---------|-------------| | vaxis init | The ONE command -- setup + map current project in one shot | | vaxis add <folder> | Register an additional project into the vault | | vaxis sync <folder> | Re-scan and update only changed files | | vaxis list | List all tracked projects with timestamps | | vaxis context <project> <note> | Export a note + neighbors for AI context | | vaxis forget <project> | Remove a project cluster from the vault | | vaxis purge | Wipe all generated data -- config, project indexes, and vault notes | | vaxis setup | Re-run the interactive setup wizard |

🤖 Model Context Protocol (MCP) Server Integration

Vaxis natively integrates a standard, stdio-based Model Context Protocol (MCP) server. This allows advanced, agentic AI assistants (like Cline, Cursor, Claude Desktop, or Windsurf) to query your Obsidian vault and codebase context automatically behind the scenes.

Rather than copy-pasting CLI commands, your AI coding agent will invoke Vaxis natively to get line-sliced, dependency-aware context on demand.

⚙️ IDE Configuration

Simply add vaxis as a stdio-based server in your AI editor's configuration:

1. Cline / VS Code

Add this block to your Cline MCP settings file (typically at %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json on Windows, or ~/.config/ equivalent on macOS/Linux):

{
  "mcpServers": {
    "vaxis": {
      "command": "vaxis",
      "args": ["mcp"],
      "disabled": false
    }
  }
}

Alternatively, you can run it via npx without a global install:

"vaxis": {
  "command": "npx",
  "args": ["-y", "@varkos/vaxis", "mcp"],
  "disabled": false
}

2. Claude Desktop

Add this to your Claude Desktop config (typically at %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "vaxis": {
      "command": "vaxis",
      "args": ["mcp"]
    }
  }
}

🛠️ Registered MCP Tools

Once enabled, your AI assistant will have access to the following native tools:

• vaxis_list_projects: Lists all active codebases currently tracked in your Obsidian vault.
• vaxis_get_context: Retreives token-efficient, line-sliced semantic context (including dependent imports and custom properties) for any specific file or feature note.
• vaxis_search_notes: Executes a high-speed fuzzy search across all vault notes to locate relevant files or historical code patterns.
• vaxis_sync_project: Instantly re-scans the target workspace directory, updating modified files and rebuilding the local dependency graph.

How It Works

1. Project Scanning

When you run vaxis init or vaxis add, the tool scans your project and creates one Obsidian note per source file. Each note contains:

• File metadata (path, type, size)
• Extracted functions, classes, and exports
• Detected imports and dependencies
• [[wikilinks]] to every file this one references

2. Vault Structure

YourVault/
  _brain.md              # Master index across all projects
  my-project/
    _index-my-project.md  # Project overview, tech stack, structure
    src/
      app.md              # Note for src/app.js
      utils.md            # Note for src/utils.js
  another-project/
    _index-another-project.md
    ...

3. GGAN Navigation (for AI Editors)

vaxis init automatically writes a .ai-rules file into your project root. This instructs AI editors to use vaxis for navigation:

# AI editors will run this to get focused context:
vaxis context my-project src/components/Hero

This prints the raw source code plus condensed summaries of all linked dependencies -- ready to paste into any AI editor as focused context.

4. Cross-Project Intelligence

When you add or sync a project, vaxis automatically detects:

• Shared dependencies across projects (e.g., both use chalk, express)
• Two-way backlinks between projects that share libraries
• These show up as "Shared with" sections in your vault notes

5. VS Code Integration

vaxis init generates a .code-workspace file that opens both your project AND the Obsidian vault in VS Code side by side. The AI rule file (.ai-rules) is fully visible in the root folder, making it extremely easy for you and your AI coding editors to inspect and reference it.

Prompting your AI Coding Agent

If you are using GitHub Copilot Chat, ChatGPT, or other chat-based AI assistants, copy-paste this simple prompt at the beginning of your chat session to tell the AI exactly how to use vaxis to navigate:

Developer Prompt to Copilot / ChatGPT / Claude: "I have set up a semantic graph index of this codebase using a tool called vaxis (@varkos/vaxis). The navigation rules are fully visible in the .ai-rules file in the project's root folder. Please read .ai-rules first, use it to guide your code generation, and directly execute vaxis context ... in your terminal to fetch precise, token-efficient graph-based context. If your terminal execution is locked or sandboxed, instruct me to run the command for you."

Uninstalling

# Remove all vaxis data (config, vault notes, AI rules):
vaxis purge

# Then uninstall the global package:
npm uninstall -g @varkos/vaxis

Privacy

All generated files are automatically added to .gitignore:

• .ai-rules -- AI rule file
• *.code-workspace -- VS Code workspace file
• .vscode/ -- VS Code settings

Your vault paths and personal configuration never leave your machine.

License

MIT