KnowledgeOps

Git-native knowledge management for production RAG.

KnowledgeOps treats your RAG knowledge base as a Git repo — version-controlled, CI/CD-pipeline'd, and deployable to any vector store. Every commit is a KB version. Every branch is an environment.

npx @knowledgeops/cli init my-kb
cd my-kb
# Add markdown files to sources/
knowledgeops sync --env dev
git add -A && git commit -m "update KB"
knowledgeops diff               # see what changed

Why KnowledgeOps?

• Git commit = KB version → no more "which KB is in prod?"
• git push triggers re-sync → no more manual re-embedding
• Branch = environment (dev/staging/prod)
• git revert = KB rollback
• Agents query your KB via MCP (Claude Code, Cursor)

Installation

# Via npx (no install needed)
npx @knowledgeops/cli init my-kb

# Or install globally
npm install -g @knowledgeops/cli
knowledgeops init my-kb

# Or run from source
git clone https://github.com/your-org/knowledgeops
cd knowledgeops && npm install && npm run build

Quick Start

# 1. Scaffold a new KB
knowledgeops init my-foundry-kb
cd my-foundry-kb

# 2. Add content
echo "# My Knowledge\n\nUseful information here." > sources/concepts/my-doc.md

# 3. Configure your vector store
# Edit knowledgeops.yaml with your endpoint

# 4. Sync
knowledgeops sync --dry-run    # preview
knowledgeops sync --env dev    # for real

# 5. Track changes in git
git add -A && git commit -m "initial KB"

Commands

knowledgeops init [directory]

Scaffold a new knowledge base repository.

Options:
  --template <name>    Template preset (default: generic)

Examples:
  knowledgeops init my-kb
  knowledgeops init .

knowledgeops sync

Chunk, embed, and upsert knowledge to your vector store.

Options:
  --env <name>         Environment to sync (dev, staging, prod)
  --dry-run            Preview changes without writing
  --force              Full re-sync (ignore cache)

Examples:
  knowledgeops sync
  knowledgeops sync --env prod
  knowledgeops sync --dry-run --env staging

knowledgeops diff

Show knowledge changes between git commits.

Options:
  --commit <sha>       Compare specific commit vs its parent
  --from <ref>         Start of comparison range (default: HEAD~1)
  --to <ref>           End of comparison range (default: HEAD)
  --stat               Summary only
  --json               Machine-readable output
  --limit <n>          Cap files processed

Examples:
  knowledgeops diff
  knowledgeops diff --commit abc1234
  knowledgeops diff --from HEAD~3 --to HEAD --stat

knowledgeops validate

Check knowledge base structure and content.

Options:
  --strict             Treat warnings as errors
  --json               Machine-readable output
  --watch              Re-run on file changes
  --fix                Auto-fix common issues

Examples:
  knowledgeops validate
  knowledgeops validate --strict --fix
  knowledgeops validate --watch

knowledgeops rollback <sha>

Revert KB to a previous git state and re-sync.

Options:
  --force              Skip confirmation
  --dry-run            Preview only
  --until <ref>        Revert multiple commits back to ref

Examples:
  knowledgeops rollback abc1234
  knowledgeops rollback abc1234 --dry-run
  knowledgeops rollback --until HEAD~3

knowledgeops status

Show KB sync state and statistics.

Examples:
  knowledgeops status

knowledgeops serve

Start MCP server for AI agent integration.

Options:
  --port <number>      HTTP port for remote agents
  --transport <type>   Transport mode (stdio or sse)
  --provider <name>    Vector store provider (default: mock)
  --token <secret>     API key for HTTP auth
  --confirm-writes     Require confirmation for kb_write/kb_update

Examples:
  knowledgeops serve                          # stdio mode
  knowledgeops serve --port 3100              # HTTP mode
  knowledgeops serve --port 3100 --token my-secret

MCP Server

The MCP server exposes KB tools to AI agents like Claude Code and Cursor.

Available Tools

| Tool | Description | |------|-------------| | kb_search | Search knowledge base chunks by keyword | | kb_read | Retrieve a full document by path | | kb_list | List all documents | | kb_status | Sync state and statistics | | kb_changed | Files changed since a git ref | | kb_diff | Diff between any two git refs | | kb_write | Write a new document and commit | | kb_update | Update an existing document and commit |

Claude Code Integration

# In your KB directory
knowledgeops serve

Add to ~/.claude/config.json:

{
  "mcpServers": {
    "knowledgeops": {
      "command": "knowledgeops",
      "args": ["serve"],
      "cwd": "/path/to/your-kb"
    }
  }
}

Cursor Integration

knowledgeops serve --port 3100 --token my-secret
# Configure Cursor MCP: http://localhost:3100 with Bearer auth

Configuration

knowledgeops.yaml

embedding:
  model: text-embedding-3-small
  provider: openai
  api_key: ${OPENAI_API_KEY}

chunk_size: 500
chunk_overlap: 50

providers:
  foundry:
    endpoint: "https://..."
    api_key: "${FOUNDRY_KEY}"
    api_version: "2025-01-01"
    index_name: "my-index"
  mock:
    enabled: true

hooks:
  post_rollback:
    - command: "curl -X POST https://hooks.slack.com/..."

Environment Files

environments/
  dev.yaml        # knowledgeops sync --env dev
  staging.yaml    # knowledgeops sync --env staging
  prod.yaml       # knowledgeops sync --env prod

Architecture

my-kb/
├── knowledgeops.yaml          # Config
├── sources/                   # Markdown knowledge
│   ├── concepts/
│   ├── procedures/
│   └── references/
├── environments/              # Per-env config overrides
├── .knowledgeops/             # Local state (SQLite)
└── .github/workflows/         # CI/CD auto-sync

Sync flow: git push → chunk markdown (SHA-tracked) → embed → incremental upsert to vector store → git tag

License

AGPL — Open-core license. The CLI is free and open source.