pi-byterover 0.1.8

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ian Pascoe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,97 @@
+# pi-byterover
+
+`pi-byterover` connects Pi sessions to ByteRover through `@byterover/brv-bridge`.
+
+It automatically recalls relevant ByteRover memory before an agent response and injects that context into the session. After useful completed turns, it persists durable facts, decisions, preferences, and technical details back to ByteRover.
+
+## Prerequisites
+
+- Pi installed.
+- ByteRover CLI installed as `brv`, or a custom executable path configured with `brvPath`.
+- A project where ByteRover can bootstrap and use `.brv` state.
+
+## Installation
+
+Install the package with Pi:
+
+```bash
+pi install npm:pi-byterover
+```
+
+For local development:
+
+```bash
+pnpm install
+pnpm build
+pi -e ./dist/index.js
+```
+
+## Configuration
+
+Configure `pi-byterover` with either a project config file or a global config file:
+
+- Project: `.pi/byterover.json`
+- Global: `~/.pi/agent/byterover.json`
+
+Project configuration takes precedence over global configuration. If no config file is present, defaults are used.
+
+```json
+{
+  "enabled": true,
+  "brvPath": "brv",
+  "searchTimeoutMs": 30000,
+  "recallTimeoutMs": 30000,
+  "persistTimeoutMs": 60000,
+  "quiet": false,
+  "autoRecall": true,
+  "autoPersist": true,
+  "manualTools": true,
+  "contextTagName": "byterover-context",
+  "recallPrompt": "Recall any relevant context that would help answer the latest user message.\nUse the recent conversation only to resolve references and intent.\nDo not restate the query in your findings.",
+  "persistPrompt": "The following is a conversation between a user and an AI assistant.\nCurate only information with lasting value: facts, decisions, technical details, preferences, or notable outcomes.\nSkip trivial messages such as greetings, acknowledgments (\"ok\", \"thanks\", \"sure\", \"got it\"), one-word replies, anything with no substantive content.",
+  "maxRecallTurns": 3,
+  "maxRecallChars": 4096
+}
+```
+
+Configuration fields:
+
+- `enabled`: Enable or disable the package without removing configuration. Defaults to `true`.
+- `brvPath`: ByteRover CLI executable path. Defaults to `brv`.
+- `searchTimeoutMs`: ByteRover search timeout in milliseconds. Defaults to `30000`.
+- `recallTimeoutMs`: ByteRover recall timeout in milliseconds. Defaults to `30000`.
+- `persistTimeoutMs`: ByteRover persist timeout in milliseconds. Defaults to `60000`.
+- `quiet`: Suppress Pi notifications for ByteRover operations. Defaults to `false`.
+- `autoRecall`: Automatically recall and inject ByteRover context before agent responses. Defaults to `true`.
+- `autoPersist`: Automatically persist useful completed conversation turns after responses. Defaults to `true`.
+- `manualTools`: Register manual ByteRover tools. Defaults to `true`.
+- `contextTagName`: XML-style tag name used for injected recall context. Defaults to `byterover-context`.
+- `recallPrompt`: Instruction text prepended to recent conversation context for automatic recall.
+- `persistPrompt`: Instruction text prepended to completed turns for automatic persistence curation.
+- `maxRecallTurns`: Maximum recent user turns used to resolve automatic recall context. Defaults to `3`.
+- `maxRecallChars`: Maximum recent conversation characters used for automatic recall. Defaults to `4096`.
+
+Numeric timeout and limit values must be positive integers. `brvPath`, `recallPrompt`, and `persistPrompt` must be non-empty strings. `contextTagName` must be a simple XML-style tag name such as `byterover-context`.
+
+Persist does not require ByteRover to be ready ahead of time. ByteRover bootstraps automatically when persist is called.
+
+## Manual Tools
+
+When `manualTools` is enabled, Pi agents can use these ByteRover tools:
+
+- `brv_recall`: Ask ByteRover to synthesize relevant memory for a query. Use it when the agent needs targeted, summarized context beyond automatic recall. Accepts optional `timeoutMs`.
+- `brv_search`: Search ByteRover memory and return ranked file-level results. Use it when the agent needs to inspect matching memory sources or compare multiple candidates. Accepts optional `limit`, `scope`, and `timeoutMs`.
+- `brv_persist`: Persist raw memory text directly into ByteRover. Use it when a durable fact, decision, preference, or technical detail should be saved immediately instead of waiting for automatic turn persistence. Defaults to fire-and-forget mode and accepts optional `timeoutMs` for long-running writes.
+
+With `autoRecall` and `autoPersist` enabled, routine memory behavior is automatic. Manual tools are best for explicit lookups, source searches, or immediate saves.
+
+## Development
+
+```bash
+pnpm install
+pnpm format:check
+pnpm lint
+pnpm test
+pnpm typecheck
+pnpm build
+```

package/dist/config-loader.d.ts

@@ -0,0 +1,17 @@
+import type * as z from "zod/v4";
+import { ConfigSchema } from "./config.js";
+export type ByteroverConfig = z.infer<typeof ConfigSchema>;
+export type LoadConfigOptions = {
+    cwd: string;
+    homeDir?: string;
+};
+export type LoadConfigResult = {
+    success: true;
+    config: ByteroverConfig;
+    source?: string;
+} | {
+    success: false;
+    source: string;
+    error: Error;
+};
+export declare const loadConfig: ({ cwd, homeDir, }: LoadConfigOptions) => Promise<LoadConfigResult>;

package/dist/config.d.ts

@@ -0,0 +1,38 @@
+import * as z from "zod/v4";
+export declare const brvGitignoreBeginMarker = "# BEGIN pi-byterover";
+export declare const brvGitignoreEndMarker = "# END pi-byterover";
+export declare const brvGitignoreRules = "# Dream state and logs\ndream-log/\ndream-state.json\ndream.lock\n\n# Review backups\nreview-backups/\n\n# Generated files\nconfig.json\n_queue_status.json\n.snapshot.json\n_manifest.json\n_index.md\n*.abstract.md\n*.overview.md\n";
+export declare const brvGitignore = "# BEGIN pi-byterover\n# Dream state and logs\ndream-log/\ndream-state.json\ndream.lock\n\n# Review backups\nreview-backups/\n\n# Generated files\nconfig.json\n_queue_status.json\n.snapshot.json\n_manifest.json\n_index.md\n*.abstract.md\n*.overview.md\n# END pi-byterover\n";
+export declare const configDefaults: {
+    enabled: boolean;
+    brvPath: string;
+    searchTimeoutMs: number;
+    recallTimeoutMs: number;
+    persistTimeoutMs: number;
+    quiet: boolean;
+    autoRecall: boolean;
+    autoPersist: boolean;
+    manualTools: boolean;
+    contextTagName: string;
+    recallPrompt: string;
+    persistPrompt: string;
+    maxRecallTurns: number;
+    maxRecallChars: number;
+};
+export declare const maxCuratedTurnCacheSize = 500;
+export declare const ConfigSchema: z.ZodDefault<z.ZodOptional<z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    brvPath: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    searchTimeoutMs: z.ZodDefault<z.ZodNumber>;
+    recallTimeoutMs: z.ZodDefault<z.ZodNumber>;
+    persistTimeoutMs: z.ZodDefault<z.ZodNumber>;
+    quiet: z.ZodDefault<z.ZodBoolean>;
+    autoRecall: z.ZodDefault<z.ZodBoolean>;
+    autoPersist: z.ZodDefault<z.ZodBoolean>;
+    manualTools: z.ZodDefault<z.ZodBoolean>;
+    contextTagName: z.ZodDefault<z.ZodString>;
+    recallPrompt: z.ZodDefault<z.ZodString>;
+    persistPrompt: z.ZodDefault<z.ZodString>;
+    maxRecallTurns: z.ZodDefault<z.ZodNumber>;
+    maxRecallChars: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>>>;

package/dist/gitignore.d.ts

@@ -0,0 +1,2 @@
+export declare const normalizeBrvGitignore: (existing: string) => string;
+export declare const ensureBrvGitignore: (cwd: string) => Promise<void>;

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+export declare const buildManualToolGuidance: (config: {
+    autoRecall: boolean;
+    autoPersist: boolean;
+}) => string;
+export default function byterover(pi: ExtensionAPI): void;