byterover-cli 2.6.0 → 3.0.1

package/.env.production

@@ -1,6 +1,7 @@
 BRV_API_BASE_URL=https://iam.byterover.dev/api/v1
 BRV_AUTHORIZATION_URL=https://iam.byterover.dev/api/v1/oidc/authorize
 BRV_COGIT_API_BASE_URL=https://v3-cgit.byterover.dev/api/v1
+BRV_GIT_REMOTE_BASE_URL=https://byterover.dev
 BRV_ISSUER_URL=https://iam.byterover.dev/api/v1/oidc
 BRV_LLM_API_BASE_URL=https://llm.byterover.dev
 BRV_TOKEN_URL=https://iam.byterover.dev/api/v1/oidc/token

package/README.md

@@ -1,15 +1,71 @@
 # ByteRover CLI
 
-Command-line interface for ByteRover — an interactive REPL for managing your project's context tree and knowledge storage. Integrates with 22+ AI coding agents.
+<div align="center">
 
-[![Version](https://img.shields.io/npm/v/byterover-cli.svg)](https://npmjs.org/package/byterover-cli)
-[![Downloads/week](https://img.shields.io/npm/dw/byterover-cli.svg)](https://npmjs.org/package/byterover-cli)
+<img src="./assets/images/logo/byterover-logo.svg" alt="ByteRover Logo" width="280" />
 
-## Installation
+<p align="center">
+<em>Interactive REPL CLI for AI-powered context memory</em>
+</p>
 
-### macOS & Linux (Recommended)
+<p align="center">
+<a href="LICENSE"><img src="https://img.shields.io/badge/License-Elastic%202.0-blue.svg" alt="License" /></a>
+<a href="https://npmjs.org/package/byterover-cli"><img src="https://img.shields.io/npm/v/byterover-cli.svg" alt="Version" /></a>
+<a href="https://npmjs.org/package/byterover-cli"><img src="https://img.shields.io/npm/dw/byterover-cli.svg" alt="Downloads" /></a>
+<a href="https://docs.byterover.dev"><img src="https://img.shields.io/badge/Docs-Documentation-green.svg" alt="Documentation" /></a>
+<a href="https://discord.com/invite/UMRrpNjh5W"><img src="https://img.shields.io/badge/Discord-Join%20Community-7289da" alt="Discord" /></a>
+</p>
 
-No Node.js required — everything is bundled.
+</div>
+
+## Overview
+
+ByteRover CLI (`brv`) gives AI coding agents persistent, structured memory. It lets developers curate project knowledge into a context tree, sync it to the cloud, and share it across tools and teammates.
+
+Run `brv` in any project directory to start an interactive REPL powered by your choice of LLM. The agent understands your codebase through an agentic map, can read and write files, execute code, and store knowledge for future sessions.
+
+📄 Read the [paper](https://arxiv.org/abs/2604.01599) for the full technical details.
+
+Or download our self-hosted PDF version of the paper [here](https://byterover.dev/paper).
+
+**Key Features:**
+
+- 🖥️ Interactive TUI with REPL interface (React/Ink)
+- 🧠 Context tree and knowledge storage management
+- 🔀 Git-like version control for the context tree (branch, commit, merge, push/pull)
+- 🤖 18 LLM providers (Anthropic, OpenAI, Google, Groq, Mistral, xAI, and more)
+- 🛠️ 24 built-in agent tools (code exec, file ops, knowledge search, memory management)
+- 🔄 Cloud sync with push/pull
+- 👀 Review workflow for curate operations (approve/reject pending changes)
+- 🔌 MCP (Model Context Protocol) integration
+- 📦 Hub and connectors ecosystem for skills and bundles
+- 🤝 Works with 22+ AI coding agents (Cursor, Claude Code, Windsurf, Cline, and more)
+- 🏢 Enterprise proxy support
+
+## Benchmark Results
+
+All benchmarks are run using the production `byterover-cli` codebase in this repository - no separate research prototype.
+
+We evaluate on two long-term conversational memory benchmarks:
+
+- **LoCoMo** - ultra-long conversations (~20K tokens, 35 sessions) testing single-hop, multi-hop, temporal, and open-domain retrieval.
+- **LongMemEval-S** - large-scale benchmark (23,867 docs, ~48 sessions per question) testing 6 memory abilities including knowledge update, temporal reasoning, and multi-session synthesis.
+
+**LoCoMo** - 96.1% overall accuracy (1,982 questions, 272 docs).
+
+**LongMemEval-S** - 92.8% overall accuracy (500 questions, 23,867 docs).
+
+<p align="center">
+<img src="assets/images/benchmarks/longmemeval-s-by-category.png" alt="LongMemEval-S Benchmark by Category" width="700" />
+</p>
+
+All metrics are LLM-as-Judge accuracy (%). See the [paper](https://arxiv.org/abs/2604.01599), or self-hosted [PDF](https://byterover.dev/paper) for full details.
+
+## Quick Start
+
+### Shell Script (macOS & Linux)
+
+No Node.js required - everything is bundled.
 
 ```bash
 curl -fsSL https://byterover.dev/install.sh | sh
@@ -17,7 +73,7 @@ curl -fsSL https://byterover.dev/install.sh | sh
 
 Supported platforms: macOS ARM64, Linux x64, Linux ARM64.
 
-### All platforms (via npm)
+### npm (All Platforms)
 
 Requires Node.js >= 20.
 
@@ -31,28 +87,198 @@ npm install -g byterover-cli
 brv --version
 ```
 
-## Quick Start
+### First Run
 
 ```bash
 cd your/project
 brv
 ```
 
-The REPL auto-configures on first run — no setup needed. Use `/curate` to add knowledge and `/query` to retrieve it:
+The REPL auto-configures on first run - no setup needed. Type `/` to discover all available commands:
 
 ```
 /curate "Auth uses JWT with 24h expiry" @src/middleware/auth.ts
 /query How is authentication implemented?
 ```
 
-Type `/` in the REPL to discover all available commands.
+## ByteRover Cloud
+
+ByteRover Cloud is a hosted platform for teams to sync, share, and manage context knowledge across projects and machines.
+Everything works locally by default - Cloud adds collaboration and persistence without changing your workflow.
+
+<p>
+<a href="https://app.byterover.dev"><img src="https://img.shields.io/badge/Try%20ByteRover%20Cloud-Free-blue?style=for-the-badge" alt="Try ByteRover Cloud" /></a>
+</p>
+
+Sign in with your ByteRover account via `/login` (TUI) or
+an [API key](https://app.byterover.dev/settings/keys) (`brv login`) to get started.
+
+- 🔄 **Team context sync** — push and pull shared knowledge across teammates
+- 📂 **Shared spaces** — organize context across multiple projects and teams
+- 💻 **Multi-machine access** — sync your context tree across devices with cloud backup
+- 🧠 **Built-in hosted LLM** — start immediately with limited free usage
+- 👥 **Team management** — manage members, spaces, and permissions via the web app
+- 📊 **Usage analytics** — track seat allocation and monthly credit consumption
+- 🔒 **SOC 2 Type II** certified infrastructure with privacy mode
+
+<details>
+<summary><h2>CLI Usage</h2></summary>
+
+### Core Workflow
+
+```bash
+brv                  # Start interactive REPL
+brv status           # Show project and daemon status
+brv curate           # Add context to knowledge storage
+brv curate view      # View curate history
+brv query            # Query context tree and knowledge
+brv review pending   # List pending review operations
+brv review approve   # Approve curate operations
+brv review reject    # Reject curate operations
+```
+
+### Sync (Legacy)
+
+```bash
+brv push             # Legacy — migrate or snapshot context to cloud
+brv pull             # Legacy — restore context from cloud snapshot
+```
+
+> Use `brv vc push` / `brv vc pull` for version-controlled sync going forward.
+
+### Version Control
+
+```bash
+brv vc init              # Initialize version control for context tree
+brv vc status            # Show version control status
+brv vc add               # Stage files for the next commit
+brv vc commit            # Save staged changes as a commit
+brv vc log               # Show commit history
+brv vc branch            # List, create, or delete branches
+brv vc checkout          # Switch branches
+brv vc merge             # Merge a branch into the current branch
+brv vc clone             # Clone a ByteRover space repository
+brv vc push              # Push commits to ByteRover cloud
+brv vc pull              # Pull commits from ByteRover cloud
+brv vc fetch             # Fetch refs from ByteRover cloud
+brv vc remote            # Show current remote origin
+brv vc remote add        # Add a named remote
+brv vc remote set-url    # Update a remote URL
+brv vc config            # Get or set commit author
+brv vc reset             # Unstage files or undo commits
+```
+
+### Providers & Models
+
+```bash
+brv providers list       # List available LLM providers
+brv providers connect    # Connect to an LLM provider
+brv providers switch     # Switch active provider
+brv providers disconnect # Disconnect a provider
+brv model list           # List available models
+brv model switch         # Switch active model
+```
+
+### Hub & Connectors
+
+```bash
+brv hub list             # List available hub packages
+brv hub install          # Install a hub package
+brv hub registry add     # Add a custom registry
+brv hub registry list    # List registries
+brv hub registry remove  # Remove a registry
+brv connectors list      # List connectors
+brv connectors install   # Install a connector
+```
+
+### Spaces (Deprecated)
+
+```bash
+brv space list       # Deprecated — use web dashboard
+brv space switch     # Deprecated — use brv vc clone
+```
+
+### Other
+
+```bash
+brv mcp              # Start MCP server
+brv login            # Authenticate to ByteRover
+brv logout           # Disconnect and clear credentials
+brv locations        # List registered projects
+brv restart          # Restart daemon
+brv debug            # Debug mode
+```
+
+Run `brv --help` for the full command reference.
+
+</details>
+
+<details>
+<summary><h2>Supported LLM Providers</h2></summary>
+
+ByteRover CLI supports 18 LLM providers out of the box. Use `brv providers connect` to set up a provider and `brv providers switch` to change the active one.
+
+| Provider | Description |
+|----------|-------------|
+| Anthropic | Claude models |
+| OpenAI | GPT models |
+| Google | Gemini models |
+| Groq | Fast inference |
+| Mistral | Mistral models |
+| xAI | Grok models |
+| Cerebras | Fast inference |
+| Cohere | Command models |
+| DeepInfra | Open-source model hosting |
+| OpenRouter | Multi-provider gateway |
+| Perplexity | Search-augmented models |
+| TogetherAI | Open-source model hosting |
+| Vercel | AI SDK provider |
+| Minimax | Minimax models |
+| Moonshot | Kimi models |
+| GLM | GLM models |
+| OpenAI-Compatible | Any OpenAI-compatible API |
+| ByteRover | ByteRover's hosted models |
+
+</details>
 
 ## Documentation
 
-Visit [**docs.byterover.dev**](https://docs.byterover.dev) for full guides on cloud sync, AI agent integrations, LLM providers, and more.
+Visit [**docs.byterover.dev**](https://docs.byterover.dev) for full guides on setup, integrations, and advanced usage.
+
+| Topic | Description |
+|-------|-------------|
+| [Getting Started](https://docs.byterover.dev) | Installation, first run, and basic usage |
+| [Cloud Sync](https://docs.byterover.dev) | Push/pull workflows and team sharing |
+| [Version Control](https://docs.byterover.dev) | Context tree branching, commits, and collaboration |
+| [LLM Providers](https://docs.byterover.dev) | Provider setup and model configuration |
+| [AI Agent Integrations](https://docs.byterover.dev) | Using ByteRover with Cursor, Claude Code, Windsurf, etc. |
+| [Hub & Connectors](https://docs.byterover.dev) | Skills, bundles, and the connector ecosystem |
+| CLI Reference | Run `brv --help` |
+
+## Contributing
+
+We welcome contributions! See our [Contributing Guide](CONTRIBUTING.md) for development setup, coding standards, and the PR workflow.
+
+## Community & Support
+
+ByteRover CLI is built and maintained by the [ByteRover team](https://byterover.dev/).
+
+- Join our [Discord](https://discord.com/invite/UMRrpNjh5W) to share projects, ask questions, or just say hi
+- [Report issues](https://github.com/campfirein/byterover-cli/issues) <!-- TODO: ENG-1575 --> on GitHub
+- If you enjoy ByteRover CLI, please give us a star on GitHub — it helps a lot!
+- Follow [@kevinnguyendn](https://x.com/kevinnguyendn) on X
+
+## Contributors
+
+<!-- TODO: ENG-1575 -->
+[![Contributors](https://contrib.rocks/image?repo=campfirein/byterover-cli&max=40&columns=10)](https://github.com/campfirein/byterover-cli/graphs/contributors)
+
+## Star History
 
-Run `brv --help` for CLI usage.
+<a href="https://star-history.com/#campfirein/byterover-cli&Date">
+  <img width="500" alt="Star History Chart" src="https://api.star-history.com/svg?repos=campfirein/byterover-cli&type=Date&v=2">
+</a>
 
----
+## License
 
-**Copyright (c) ByteRover**
+Elastic License 2.0. See [LICENSE](LICENSE) for full terms.

package/dist/agent/core/domain/knowledge/conflict-detector.d.ts

@@ -0,0 +1,38 @@
+import type { ContextData } from '../../../../server/core/domain/knowledge/markdown-writer.js';
+/**
+ * Summary of detected structural loss when comparing existing vs proposed content.
+ */
+export type StructuralLoss = {
+    hasLoss: boolean;
+    /** Number of rawConcept array items (changes, files) that would be lost */
+    lostArrayItems: number;
+    /** Number of narrative fields that would be lost */
+    lostNarrativeFields: number;
+    /** Number of rawConcept scalar fields that would be lost */
+    lostRawConceptFields: number;
+    /** Number of relations that would be lost */
+    lostRelations: number;
+    /** Number of snippets that would be lost */
+    lostSnippets: number;
+};
+/**
+ * Detect structural loss between existing content and proposed content.
+ *
+ * Only flags when existing content would be LOST, not when new content is added.
+ * This prevents false positives when the LLM is enriching content.
+ *
+ * @param existing - Parsed content from the existing file
+ * @param proposed - Proposed new content from the curate operation
+ * @returns StructuralLoss summary
+ */
+export declare function detectStructuralLoss(existing: ContextData, proposed: ContextData): StructuralLoss;
+/**
+ * Derive the structural impact level from detected loss.
+ *
+ * - Any structural loss → 'high'
+ * - No loss → 'low'
+ *
+ * @param loss - Structural loss summary from detectStructuralLoss
+ * @returns Impact level derived from structural evidence
+ */
+export declare function deriveImpactFromLoss(loss: StructuralLoss): 'high' | 'low';

package/dist/agent/core/domain/knowledge/conflict-detector.js

@@ -0,0 +1,71 @@
+import { normalize } from './utils.js';
+/**
+ * Find items in `existing` that are not in `proposed` (case-insensitive).
+ */
+function countLostItems(existing, proposed) {
+    const proposedSet = new Set(proposed.map((s) => normalize(s)));
+    return existing.filter((item) => !proposedSet.has(normalize(item))).length;
+}
+/**
+ * Count narrative fields that exist in `existing` but are absent in `proposed`.
+ */
+function countLostNarrativeFields(existing, proposed) {
+    if (!existing)
+        return 0;
+    const fields = ['dependencies', 'examples', 'highlights', 'rules', 'structure'];
+    return fields.filter((field) => existing[field] && !proposed?.[field]).length;
+}
+/**
+ * Count rawConcept scalar fields and array items that would be lost.
+ */
+function countLostRawConceptFields(existing, proposed) {
+    if (!existing)
+        return { arrayItems: 0, scalars: 0 };
+    const scalarFields = ['author', 'flow', 'task', 'timestamp'];
+    const scalars = scalarFields.filter((field) => existing[field] && !proposed?.[field]).length;
+    const existingChanges = existing.changes ?? [];
+    const existingFiles = existing.files ?? [];
+    const proposedChanges = proposed?.changes ?? [];
+    const proposedFiles = proposed?.files ?? [];
+    const arrayItems = countLostItems(existingChanges, proposedChanges) + countLostItems(existingFiles, proposedFiles);
+    return { arrayItems, scalars };
+}
+/**
+ * Detect structural loss between existing content and proposed content.
+ *
+ * Only flags when existing content would be LOST, not when new content is added.
+ * This prevents false positives when the LLM is enriching content.
+ *
+ * @param existing - Parsed content from the existing file
+ * @param proposed - Proposed new content from the curate operation
+ * @returns StructuralLoss summary
+ */
+export function detectStructuralLoss(existing, proposed) {
+    const lostSnippets = countLostItems(existing.snippets ?? [], proposed.snippets ?? []);
+    const lostRelations = countLostItems(existing.relations ?? [], proposed.relations ?? []);
+    const lostNarrativeFields = countLostNarrativeFields(existing.narrative, proposed.narrative);
+    const { arrayItems: lostArrayItems, scalars: lostRawConceptFields } = countLostRawConceptFields(existing.rawConcept, proposed.rawConcept);
+    const hasLoss = lostSnippets > 0 || lostRelations > 0 || lostNarrativeFields > 0 || lostRawConceptFields > 0 || lostArrayItems > 0;
+    return {
+        hasLoss,
+        lostArrayItems,
+        lostNarrativeFields,
+        lostRawConceptFields,
+        lostRelations,
+        lostSnippets,
+    };
+}
+/**
+ * Derive the structural impact level from detected loss.
+ *
+ * - Any structural loss → 'high'
+ * - No loss → 'low'
+ *
+ * @param loss - Structural loss summary from detectStructuralLoss
+ * @returns Impact level derived from structural evidence
+ */
+export function deriveImpactFromLoss(loss) {
+    if (!loss.hasLoss)
+        return 'low';
+    return 'high';
+}

package/dist/agent/core/domain/knowledge/conflict-resolver.d.ts

@@ -0,0 +1,17 @@
+import type { ContextData } from '../../../../server/core/domain/knowledge/markdown-writer.js';
+import type { StructuralLoss } from './conflict-detector.js';
+/**
+ * Auto-resolve structural loss by merging existing content into proposed content.
+ *
+ * Resolution strategy:
+ * - Arrays (snippets, relations, changes, files): Union merge with deduplication
+ * - Scalars (narrative fields, rawConcept scalars): Proposed wins; preserve existing if proposed empty
+ *
+ * Only runs when `loss.hasLoss` is true. When no loss is detected, returns proposed as-is.
+ *
+ * @param existing - Parsed content from the existing file (before update)
+ * @param proposed - Proposed new content from the curate operation
+ * @param loss - Structural loss summary from detectStructuralLoss
+ * @returns Resolved content with lost items merged back in
+ */
+export declare function resolveStructuralLoss(existing: ContextData, proposed: ContextData, loss: StructuralLoss): ContextData;

package/dist/agent/core/domain/knowledge/conflict-resolver.js

@@ -0,0 +1,118 @@
+import { normalize } from './utils.js';
+/**
+ * Merge two arrays with case-insensitive deduplication.
+ * Existing items come first (preserves original order), then new items from proposed.
+ */
+function mergeArraysWithDedup(existing, proposed) {
+    const seen = new Set();
+    const result = [];
+    for (const item of existing) {
+        const key = normalize(item);
+        if (!seen.has(key)) {
+            seen.add(key);
+            result.push(item);
+        }
+    }
+    for (const item of proposed) {
+        const key = normalize(item);
+        if (!seen.has(key)) {
+            seen.add(key);
+            result.push(item);
+        }
+    }
+    return result;
+}
+/**
+ * Merge narrative fields.
+ * Use proposed if provided, otherwise preserve existing (prevents data loss).
+ */
+function mergeNarrative(existing, proposed) {
+    if (!existing && !proposed)
+        return undefined;
+    if (!existing)
+        return proposed;
+    if (!proposed)
+        return existing;
+    const merged = {};
+    const fields = ['dependencies', 'examples', 'highlights', 'rules', 'structure'];
+    for (const field of fields) {
+        const value = proposed[field] ?? existing[field];
+        if (value !== undefined) {
+            // Type assertion needed due to heterogeneous union (string | Array)
+            ;
+            merged[field] = value;
+        }
+    }
+    // Diagrams: union merge by content
+    const existingDiagrams = existing.diagrams ?? [];
+    const proposedDiagrams = proposed.diagrams ?? [];
+    if (existingDiagrams.length > 0 || proposedDiagrams.length > 0) {
+        const seen = new Set(existingDiagrams.map((d) => normalize(d.content)));
+        const mergedDiagrams = [...existingDiagrams];
+        for (const diagram of proposedDiagrams) {
+            if (!seen.has(normalize(diagram.content))) {
+                mergedDiagrams.push(diagram);
+            }
+        }
+        merged.diagrams = mergedDiagrams;
+    }
+    return Object.keys(merged).length > 0 ? merged : undefined;
+}
+/**
+ * Merge rawConcept fields.
+ * Scalars: use proposed if provided, otherwise preserve existing.
+ * Arrays (changes, files): union merge with deduplication.
+ */
+function mergeRawConcept(existing, proposed) {
+    if (!existing && !proposed)
+        return undefined;
+    if (!existing)
+        return proposed;
+    if (!proposed)
+        return existing;
+    const merged = {};
+    // Scalar fields: proposed wins, fall back to existing
+    const scalarFields = ['author', 'flow', 'task', 'timestamp'];
+    for (const field of scalarFields) {
+        const value = proposed[field] ?? existing[field];
+        if (value !== undefined) {
+            ;
+            merged[field] = value;
+        }
+    }
+    // patterns: proposed wins, fall back to existing
+    merged.patterns = proposed.patterns ?? existing.patterns;
+    // Array fields: union merge
+    const mergedChanges = mergeArraysWithDedup(existing.changes ?? [], proposed.changes ?? []);
+    if (mergedChanges.length > 0)
+        merged.changes = mergedChanges;
+    const mergedFiles = mergeArraysWithDedup(existing.files ?? [], proposed.files ?? []);
+    if (mergedFiles.length > 0)
+        merged.files = mergedFiles;
+    return Object.keys(merged).length > 0 ? merged : undefined;
+}
+/**
+ * Auto-resolve structural loss by merging existing content into proposed content.
+ *
+ * Resolution strategy:
+ * - Arrays (snippets, relations, changes, files): Union merge with deduplication
+ * - Scalars (narrative fields, rawConcept scalars): Proposed wins; preserve existing if proposed empty
+ *
+ * Only runs when `loss.hasLoss` is true. When no loss is detected, returns proposed as-is.
+ *
+ * @param existing - Parsed content from the existing file (before update)
+ * @param proposed - Proposed new content from the curate operation
+ * @param loss - Structural loss summary from detectStructuralLoss
+ * @returns Resolved content with lost items merged back in
+ */
+export function resolveStructuralLoss(existing, proposed, loss) {
+    if (!loss.hasLoss)
+        return proposed;
+    return {
+        ...proposed,
+        narrative: mergeNarrative(existing.narrative, proposed.narrative),
+        rawConcept: mergeRawConcept(existing.rawConcept, proposed.rawConcept),
+        relations: mergeArraysWithDedup(existing.relations ?? [], proposed.relations ?? []),
+        snippets: mergeArraysWithDedup(existing.snippets ?? [], proposed.snippets ?? []),
+    };
+}

package/dist/agent/core/domain/knowledge/utils.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Normalize a string for comparison (trim and lowercase).
+ */
+export declare function normalize(s: string): string;

package/dist/agent/core/domain/knowledge/utils.js

@@ -0,0 +1,6 @@
+/**
+ * Normalize a string for comparison (trim and lowercase).
+ */
+export function normalize(s) {
+    return s.trim().toLowerCase();
+}

package/dist/agent/core/interfaces/i-curate-service.d.ts

@@ -114,10 +114,14 @@ export type CurateOperationType = 'ADD' | 'DELETE' | 'MERGE' | 'UPDATE' | 'UPSER
  * Single curate operation.
  */
 export interface CurateOperation {
+    /** LLM-assessed confidence in the accuracy and completeness of this operation */
+    confidence?: 'high' | 'low';
     /** Content for ADD/UPDATE operations */
     content?: CurateContent;
     /** Domain-level context for new domains */
     domainContext?: CurateDomainContext;
+    /** Estimated scope of impact of this knowledge change */
+    impact?: 'high' | 'low';
     /** Target path for MERGE operation */
     mergeTarget?: string;
     /** Title of the target file for MERGE operation */
@@ -128,6 +132,8 @@ export interface CurateOperation {
     reason: string;
     /** Subtopic-level context for new subtopics */
     subtopicContext?: CurateSubtopicContext;
+    /** One-line semantic summary of what the knowledge file contains after this operation */
+    summary?: string;
     /** Title for the context file (becomes {title}.md) */
     title?: string;
     /** Topic-level context for new topics */