Claude Code Integration

1. Install vaultctl

git clone https://github.com/testing-in-production/vaultctl.git
cd vaultctl
npm install && npm run build
alias vaultctl="node $PWD/packages/cli/dist/index.js"
vaultctl config set vault ~/path/to/your/vault

2. Register the MCP Server

claude mcp add vaultctl -s user -- node /path/to/vaultctl/packages/mcp/dist/index.js

Or add manually to your Claude config:

// ~/.claude.json
{
  "mcpServers": {
    "vaultctl": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/vaultctl/packages/mcp/dist/index.js"],
      "env": {
        "VAULTCTL_PATH": "/path/to/your/vault"
      }
    }
  }
}

3. Add a CLAUDE.md

Create a CLAUDE.md in your project root. Claude Code reads this automatically at session start. Keep it under 200 lines.

# My Project

One-line description of what this project does.

## Stack

- Language, framework, runtime
- Database, cache, message queue
- Testing framework
- Node/Python/Go version

## Commands

```bash
npm run build          # Build
npm run test           # Run tests
npm run dev            # Dev server
```

## Project Structure

```
src/
  models/     Data models and database schema
  routes/     API endpoints
  services/   Business logic
  utils/      Shared utilities
```

## Key Patterns

- **Config**: Where config lives, how it's loaded
- **Auth**: How authentication works
- **Testing**: Patterns, fixtures, mocking approach
- **Deployment**: Where it runs, how to deploy

vaultctl organizes knowledge into three tiers, each with different access patterns:

Tier 1: Vault (read/write)

Your markdown vault. Structured notes with YAML frontmatter, [[wikilinks]], and tags. Full CRUD via CLI, API, and MCP. Good for decisions, meeting notes, project briefs, reference material.

vaultctl search "database migration"
vaultctl read "decisions/use-postgres.md"
vaultctl create --template decision "Switch to PostgreSQL"

Tier 2: Skills (read-only)

Claude Code skill files in .claude/skills/. Procedural knowledge: how to do things, not what things are. Skills are indexed and searchable through vaultctl.

.claude/skills/
  express-5-migration.md     # Express 4 to 5 breaking changes
  docker-monorepo.md          # Multi-stage Docker builds for monorepos
  testing-patterns.md         # Project-specific test conventions

Tier 3: Memory (read-only)

Claude Code memory files in .claude/projects/*/memory/. Fast context that persists across conversations. Memory files are indexed and searchable through vaultctl.

.claude/projects/-Users-you-Projects-myapp/memory/
  MEMORY.md       # Always loaded (keep under 200 lines)
  patterns.md     # Reusable patterns discovered across sessions
  decisions.md    # Why we chose X over Y

When the MCP server is registered, Claude Code gets access to 27 tools:

Knowledge Operations

Session Management

Sessions are automatically documented in daily journal notes via the Stop hook. When a session ends, activity-flush.sh posts a digest to the server, which appends a structured entry to 05_Journal/daily/YYYY-MM-DD.md (auto-created with proper frontmatter if it does not exist). No manual action needed.

Health and Governance

Intelligence

Utilities

If MCP is unavailable (server not running, stale process), use the CLI directly:

vaultctl search "keyword" --type project --status active
vaultctl read "path/to/note.md"
vaultctl health --check broken-links
vaultctl schema diff
vaultctl tags list
vaultctl info

All CLI output is JSON by default (AI-friendly). Add --format table for human-readable output.

MEMORY.md (auto-loaded)

Create a MEMORY.md in your project's memory directory. Claude Code loads this automatically. Use it for fast context that should be available in every session.

# Memory

## Project
- **Name**: Brief description
- **Stack**: Key technologies
- **Repo**: Where the code lives

## Preferences
- Testing framework and patterns
- Commit message style
- Code style preferences

## Active Work
- Current focus area
- Recent decisions (link to vault notes for details)

## Key Files
- `src/config.ts` - All configuration
- `src/db/schema.ts` - Database schema
- `tests/fixtures/` - Test data

Topic Files

For detailed knowledge that doesn't need to be in every conversation, use separate topic files:

memory/
  MEMORY.md          # Always loaded, keep concise
  patterns.md        # Reusable patterns
  decisions.md       # Decision log
  infrastructure.md  # Deployment, servers, networking

Reference these from MEMORY.md so Claude knows they exist:

## Topic Files
- **patterns.md**: Cross-project patterns organized by concept
- **decisions.md**: Decision log with rationale
- **infrastructure.md**: Servers, deployment, networking

Skills are procedural knowledge: step-by-step instructions for specific tasks. Claude Code reads them when relevant.

Skill Structure

# Skill Name

One-line description. Use when: (1) trigger condition, (2) trigger condition.

## Steps

1. Do this first
2. Then do this
3. Finally do this

## Common Pitfalls

- Thing that looks right but is wrong
- Edge case to watch for

Good Skill Candidates

• Framework migration gotchas (Express 4 to 5, React class to hooks)
• Deployment procedures for your infrastructure
• Debugging playbooks for recurring issues
• API quirks in tools you use (gray-matter date parsing, Docker layer caching)
• Project-specific conventions (test patterns, naming, file organization)

Bad Skill Candidates

• Generic programming knowledge (Claude already knows this)
• One-time procedures you won't repeat
• Information that changes frequently (put this in vault notes instead)

vaultctl enforces note types via frontmatter schema. The default schema includes 11 types:

Universal Frontmatter Fields

---
type: project
status: active
tags:
  - engineering
  - backend
created: 2025-01-15
updated: 2025-03-04
summary: Brief description of the project
confidence: high
source_ai: manual
---

The schema in _meta/schema.yaml is fixed by design. Verify schema alignment with vaultctl schema diff.

For programmatic access beyond the CLI, run the server:

VAULT_PATH=/path/to/vault node /path/to/vaultctl/packages/server/dist/index.js

MCP server not responding

# Kill stale processes
pkill -f "vaultctl.*mcp"

# Verify the build exists
ls /path/to/vaultctl/packages/mcp/dist/index.js

# Test manually
VAULTCTL_PATH=/path/to/vault node /path/to/vaultctl/packages/mcp/dist/index.js

For persistent reliability, use the MCP health monitor LaunchAgent. It periodically checks for orphaned MCP processes and restarts them, preventing stale connections from blocking Claude Code sessions.

Vault not found

# Check config
vaultctl config get vault

# Set it
vaultctl config set vault /path/to/your/vault

# Or use environment variable
export VAULTCTL_PATH=/path/to/your/vault

Health check failures

# See all issues
vaultctl health --json

# Auto-fix what's fixable
vaultctl health --fix

# Check specific issue
vaultctl health --check broken-links