ContextDB.nvim

A Neovim plugin for integrating with ContextDB - an operation-based document database with stable addressing for character-level permalinks and real-time collaboration.

Features

• Automatic Operation Capture: Track text changes, file operations, and development events
• Stable Addressing: Create permanent links to specific code locations
• Full-text Search: Search across all captured operations and documents
• Telescope Integration: Beautiful search interface (if telescope.nvim is available)
• Batch Processing: Efficient operation batching to minimize API calls
• Session Tracking: Monitor development sessions and productivity patterns

Requirements

• Neovim >= 0.8.0
• ContextDB server running (see main README)
• curl command available
• Optional: telescope.nvim for enhanced search UI

Installation

Using LazyVim

Create a new file in your ~/.config/nvim/lua/plugins/ directory (e.g., contextdb.lua):

-- ~/.config/nvim/lua/plugins/contextdb.lua
return {
  {
    "jeremytregunna/contextdb.nvim",
    -- For local development, use dir instead of the repository URL:
    -- dir = "/path/to/contextdb/plugin/contextdb.nvim",
    event = "VeryLazy",  -- Load after LazyVim startup
    dependencies = {
      "nvim-telescope/telescope.nvim",  -- Optional but recommended
    },
    keys = {
      { "<leader>cp", "<cmd>ContextDBPermalink<cr>", desc = "Create ContextDB Permalink" },
      { "<leader>cs", "<cmd>ContextDBSearch ", desc = "Search ContextDB" },
      { "<leader>ct", "<cmd>ContextDBToggle<cr>", desc = "Toggle ContextDB" },
    },
    opts = {
      server_url = "http://localhost:8080/api/v1",
      api_key = os.getenv("CONTEXTDB_API_KEY"),  -- Optional
      addressing = {
        permalink_keybind = "<leader>cp",
      },
      search = {
        telescope_integration = true,
      },
    },
    config = function(_, opts)
      require('contextdb').setup(opts)
    end,
  }
}

Using lazy.nvim (Standalone)

{
  'jeremytregunna/contextdb.nvim',
  config = function()
    require('contextdb').setup({
      server_url = 'http://localhost:8080/api/v1',
      api_key = os.getenv('CONTEXTDB_API_KEY'),
    })
  end,
}

Using packer.nvim

use {
  'jeremytregunna/contextdb.nvim',
  config = function()
    require('contextdb').setup()
  end
}

Configuration

Environment Setup

ContextDB API key is optional. The plugin works without authentication, but you can enable it if needed:

export CONTEXTDB_API_KEY="your-api-key-here"  # Optional

Plugin Configuration

require('contextdb').setup({
  enabled = true,
  server_url = 'http://localhost:8080/api/v1',
  api_key = os.getenv('CONTEXTDB_API_KEY'),  -- Optional
  author = vim.fn.system('whoami'):gsub('\n', ''),

  capture = {
    text_changes = true,      -- Track text modifications
    file_operations = true,   -- Track file create/save/delete
    git_events = false,       -- Git integration (future)
    search_queries = true,    -- Log search operations
    cursor_movements = false, -- Track significant cursor jumps
    diagnostics = true,       -- Capture LSP diagnostics
  },

  filters = {
    min_change_size = 3,                    -- Ignore tiny changes
    exclude_filetypes = { 'help', 'terminal' },
    exclude_patterns = {
      '.*node_modules.*',
      '.*%.git.*',
      '.*%.tmp$',
    },
  },

  batching = {
    enabled = true,         -- Batch operations for efficiency
    max_batch_size = 10,    -- Send after 10 operations
    flush_interval_ms = 1000, -- Or send after 1 second
  },

  addressing = {
    auto_permalink = false,           -- Don't auto-create permalinks
    permalink_keybind = '<leader>cp', -- Keybind for manual permalinks
  },

  search = {
    telescope_integration = true, -- Use telescope if available
    default_limit = 50,          -- Default search result limit
  },
})

Usage

Commands

• :ContextDBStatus - Show connection status and operation count
• :ContextDBSearch <query> - Search across all operations and documents
• :ContextDBToggle - Enable/disable the plugin
• :ContextDBPermalink - Create a permalink to current cursor location

Default Keybindings

• <leader>cp - Create permalink (if enabled in config)

Lua API

local contextdb = require('contextdb')

-- Manual operation creation
contextdb.client.create_operation({
  type = 'insert',
  content = 'Hello, world!',
  document_id = vim.api.nvim_buf_get_name(0),
  -- ... other fields
})

-- Search operations
contextdb.search.search('function definition')

-- Create permalink
contextdb.addressing.create_permalink()

-- Advanced search with filters
contextdb.search.search_operations({
  author = 'john-doe',
  type = 'insert',
  since = '2024-01-01',
})

Integration Patterns

Automatic Event Capture

The plugin automatically captures:

• Text Changes: Insertions, deletions, and modifications with context
• File Operations: File creation, saving, deletion, and buffer switching
• LSP Diagnostics: Error and warning counts with severity levels
• Search Queries: Logged as operations for context building
• Session Events: Development session start/end tracking

Operation Classification

Operations are automatically classified by type:

• text_edit - Code modifications
• file_create, file_save, file_delete - File operations
• file_open - Buffer/file access
• search_query - Search operations
• permalink_create - Stable address creation
• session_start - Development session tracking

Context Enrichment

Each operation includes rich metadata:

• Buffer and cursor context
• Git branch and status (when available)
• Session and timestamp information
• File type and editor state
• Neovim version and environment

Search Integration

With Telescope

If telescope.nvim is installed, searches open in a beautiful picker interface:

• Navigate results with <C-j> and <C-k>
• Jump to location with <CR>
• Create permalink with <C-p>

Without Telescope

Search results populate the quickfix list for easy navigation.

Troubleshooting

Connection Issues

1. Ensure ContextDB server is running:

   curl http://localhost:8080/api/v1/health

2. Check your API key is set (if using authentication):

   echo $CONTEXTDB_API_KEY

3. Verify plugin status:

   :ContextDBStatus

Performance

If the plugin feels slow:

1. Increase batching limits:

   batching = {
     max_batch_size = 20,
     flush_interval_ms = 2000,
   }

2. Add more exclusion filters:

   filters = {
     min_change_size = 5,
     exclude_patterns = { '.*large_file_pattern.*' }
   }

3. Disable cursor movement tracking:

   capture = {
     cursor_movements = false,
   }

Development

To contribute or modify the plugin:

1. Fork the repository
2. Make changes
3. Test with a local ContextDB server
4. Submit a pull request

Testing

# Start ContextDB server
cd /path/to/contextdb
./contextdb

# In another terminal, test the plugin
nvim -u minimal.lua test_file.txt

Create minimal.lua:

-- Add your plugin to the runtime path
vim.opt.rtp:append('/path/to/contextdb/plugin/contextdb.nvim')

-- Set up the plugin
require('contextdb').setup({
  server_url = 'http://localhost:8080/api/v1',
  api_key = 'test-key',
})

-- Enable debugging
vim.g.contextdb_debug = true

License

Copyright (C) 2025 Jeremy Tregunna

Licensed under the Apache License, Version 2.0. See LICENSE for details.