@spinabot/brigade 0.1.2 → 1.0.1

package/dist/agents/memory/storage.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Brigade memory storage — the abstraction Primitive #4 ships and Phase 2
+ * (DB-backed multi-user) swaps out.
+ *
+ * Deliberately narrow v1 surface: `search` + `read` + `status`. No
+ * embeddings, no SQLite, no vector index in v1 — `search` is a lexical
+ * (term-overlap) scan over `MEMORY.md` (persona-level, always also
+ * injected into the prompt) plus the daily notes under
+ * `memory/YYYY-MM-DD.md`.
+ *
+ * Writing is NOT part of this interface. Durable structured facts are
+ * persisted via the `write_memory` tool (see `memory-tools.ts`), which
+ * routes through `FactStore` / `MemoryCapability`. The agent may also
+ * append free-form notes directly to `memory/<today>.md` using its
+ * ordinary `write` / `edit` tool — Pi's session cwd is the workspace dir,
+ * so `write({path: "memory/2026-05-21.md"})` lands in the right place.
+ *
+ * Phase 2 implements `BrigadeStorage` over a database. Because the contract
+ * is just these three methods, the memory tools (`recall_memory`,
+ * `read_memory`) and the recall prompt section don't change — they depend
+ * on the interface, not the filesystem.
+ */
+/** One scored hit from a memory search. */
+export interface MemorySearchResult {
+    /** Path RELATIVE to the workspace dir, e.g. "MEMORY.md" or "memory/2026-05-21.md". */
+    relPath: string;
+    /** 1-based line where the matched chunk starts. */
+    startLine: number;
+    /** 1-based line where the matched chunk ends (inclusive). */
+    endLine: number;
+    /** Relevance score (higher = better). v1 = term-overlap count, see scoreChunk. */
+    score: number;
+    /** The matched text chunk, trimmed. */
+    snippet: string;
+}
+/** Result of a bounded memory-file read. */
+export interface MemoryReadResult {
+    /** Path RELATIVE to the workspace dir. */
+    relPath: string;
+    /** The (possibly windowed) file text. */
+    text: string;
+    /** True when the read was windowed and more lines exist after `nextFrom`. */
+    truncated: boolean;
+    /** 1-based line the returned window starts at. */
+    from: number;
+    /** Number of lines returned. */
+    lines: number;
+    /** 1-based line a follow-up read should start at, when truncated. */
+    nextFrom?: number;
+}
+/** Backend health/shape snapshot for `brigade doctor` / `brigade status`. */
+export interface MemoryStatus {
+    /** v1 is always "file"; Phase 2 DB-backed impl reports "db". */
+    backend: "file";
+    /** Number of memory files present (MEMORY.md + memory/*.md). */
+    fileCount: number;
+    /** Total bytes across all memory files. */
+    totalBytes: number;
+    /** Absolute path to the memory corpus root (the workspace dir). */
+    root: string;
+}
+export interface MemorySearchOptions {
+    /** Max results to return. Default 8. */
+    maxResults?: number;
+    /** Drop hits below this score. Default 1 (at least one query term present). */
+    minScore?: number;
+}
+export interface MemoryReadOptions {
+    /** 1-based line to start at. Default 1. */
+    from?: number;
+    /** Max lines to return. Default 200. */
+    lines?: number;
+}
+/**
+ * The storage contract. Filesystem impl ships in v1; DB impl in Phase 2.
+ * Consumers (the memory tools + the recall prompt) depend ONLY on this.
+ */
+export interface BrigadeStorage {
+    search(query: string, opts?: MemorySearchOptions): Promise<MemorySearchResult[]>;
+    read(relPath: string, opts?: MemoryReadOptions): Promise<MemoryReadResult>;
+    status(): Promise<MemoryStatus>;
+}
+/**
+ * Thrown when a caller asks to read a path outside the allowed memory
+ * corpus (anything that isn't `MEMORY.md` or a file under `memory/`).
+ * The memory tools translate this into a tool-result error the model sees.
+ */
+export declare class BrigadeMemoryPathError extends Error {
+    constructor(message: string);
+}
+/**
+ * Filesystem-backed `BrigadeStorage`. The corpus is rooted at the agent's
+ * workspace dir:
+ *   - `MEMORY.md`            (optional; present once the agent writes it)
+ *   - `memory/*.md`          (daily notes the agent appends to)
+ *
+ * Read-only — writes go through Pi's `write`/`edit` tool, not here.
+ */
+export declare class FileMemoryStore implements BrigadeStorage {
+    private readonly workspaceDir;
+    constructor(workspaceDir: string);
+    /**
+     * Lexical search across MEMORY.md + memory/*.md. Splits each file into
+     * blank-line-separated chunks, scores each chunk by how many distinct
+     * query terms it contains, and returns the top `maxResults` chunks
+     * across all files. No embeddings — this is the v1 builtin backend.
+     */
+    search(query: string, opts?: MemorySearchOptions): Promise<MemorySearchResult[]>;
+    /**
+     * Read a corpus file for SEARCH with a byte cap. Files over
+     * `MAX_SEARCH_FILE_BYTES` are read head-only so an unbounded daily note
+     * can't OOM the process. Returns undefined when the file can't be read.
+     */
+    private readForSearch;
+    /**
+     * Bounded read of a single memory file. `relPath` must be `MEMORY.md`
+     * or a file under `memory/` — anything else throws
+     * `BrigadeMemoryPathError` (no reading arbitrary workspace files
+     * through the memory tool).
+     */
+    read(relPath: string, opts?: MemoryReadOptions): Promise<MemoryReadResult>;
+    status(): Promise<MemoryStatus>;
+    /**
+     * List the corpus files (relative paths): MEMORY.md if present, plus
+     * every `*.md` under `memory/`. Sorted for deterministic search output.
+     */
+    private listCorpusFiles;
+    /**
+     * Validate + normalise a caller-supplied relPath. Accepts only
+     * `MEMORY.md` (case-insensitive) or a `*.md` directly under `memory/`.
+     * Rejects traversal, absolute paths, nested subdirs, and non-md files.
+     */
+    private assertCorpusPath;
+}
+/** Lowercase + split on non-word chars; drop terms shorter than 2 chars. */
+export declare function tokenize(text: string): string[];
+interface Chunk {
+    text: string;
+    startLine: number;
+    endLine: number;
+}
+/**
+ * Split a file into blank-line-separated chunks, tracking 1-based line
+ * numbers so search hits can cite where they came from. A run of one or
+ * more blank lines is the separator.
+ */
+export declare function splitIntoChunks(text: string): Chunk[];
+/**
+ * Score a chunk by how many DISTINCT query terms it contains, plus a
+ * small bonus for total term frequency. Distinct-term coverage dominates
+ * so a chunk mentioning all query terms once beats a chunk repeating one
+ * term many times.
+ */
+export declare function scoreChunk(chunkText: string, queryTerms: string[]): number;
+export {};
+//# sourceMappingURL=storage.d.ts.map

package/dist/agents/memory/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../../src/agents/memory/storage.ts"],"names":[],"mappings":"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"}

package/dist/agents/memory/storage.js

@@ -0,0 +1,359 @@
+/**
+ * Brigade memory storage — the abstraction Primitive #4 ships and Phase 2
+ * (DB-backed multi-user) swaps out.
+ *
+ * Deliberately narrow v1 surface: `search` + `read` + `status`. No
+ * embeddings, no SQLite, no vector index in v1 — `search` is a lexical
+ * (term-overlap) scan over `MEMORY.md` (persona-level, always also
+ * injected into the prompt) plus the daily notes under
+ * `memory/YYYY-MM-DD.md`.
+ *
+ * Writing is NOT part of this interface. Durable structured facts are
+ * persisted via the `write_memory` tool (see `memory-tools.ts`), which
+ * routes through `FactStore` / `MemoryCapability`. The agent may also
+ * append free-form notes directly to `memory/<today>.md` using its
+ * ordinary `write` / `edit` tool — Pi's session cwd is the workspace dir,
+ * so `write({path: "memory/2026-05-21.md"})` lands in the right place.
+ *
+ * Phase 2 implements `BrigadeStorage` over a database. Because the contract
+ * is just these three methods, the memory tools (`recall_memory`,
+ * `read_memory`) and the recall prompt section don't change — they depend
+ * on the interface, not the filesystem.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+const DEFAULT_MAX_RESULTS = 8;
+const DEFAULT_MIN_SCORE = 1;
+const DEFAULT_READ_LINES = 200;
+/** Hard cap so a recall_memory call can't dump a giant note into the context. */
+const MAX_READ_LINES = 1000;
+/**
+ * Per-file byte cap for SEARCH reads. Daily notes are append-only and can
+ * grow unbounded; without this a single 10 MB note would be slurped +
+ * tokenised on every recall_memory call. Matches the precedent in
+ * `workspace-loader.ts` (2 MB). Files larger than this are read head-only
+ * for search — the head is where the most recent appends land if the agent
+ * writes newest-first, and search still works on the truncated head.
+ */
+const MAX_SEARCH_FILE_BYTES = 2 * 1024 * 1024;
+/**
+ * Per-snippet character cap so one giant blank-line-free paragraph can't
+ * become a 50 KB snippet. Longer chunks are truncated with an ellipsis.
+ */
+const MAX_SNIPPET_CHARS = 1500;
+/**
+ * Total-output character ceiling across all returned snippets, so a search
+ * can't flood the model's context. Results past this budget are dropped
+ * (they're the lowest-scored, since results are sorted before slicing).
+ */
+const MAX_TOTAL_SNIPPET_CHARS = 8000;
+/**
+ * Thrown when a caller asks to read a path outside the allowed memory
+ * corpus (anything that isn't `MEMORY.md` or a file under `memory/`).
+ * The memory tools translate this into a tool-result error the model sees.
+ */
+export class BrigadeMemoryPathError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "BrigadeMemoryPathError";
+    }
+}
+/**
+ * Filesystem-backed `BrigadeStorage`. The corpus is rooted at the agent's
+ * workspace dir:
+ *   - `MEMORY.md`            (optional; present once the agent writes it)
+ *   - `memory/*.md`          (daily notes the agent appends to)
+ *
+ * Read-only — writes go through Pi's `write`/`edit` tool, not here.
+ */
+export class FileMemoryStore {
+    workspaceDir;
+    constructor(workspaceDir) {
+        this.workspaceDir = path.resolve(workspaceDir);
+    }
+    /**
+     * Lexical search across MEMORY.md + memory/*.md. Splits each file into
+     * blank-line-separated chunks, scores each chunk by how many distinct
+     * query terms it contains, and returns the top `maxResults` chunks
+     * across all files. No embeddings — this is the v1 builtin backend.
+     */
+    async search(query, opts = {}) {
+        const terms = tokenize(query);
+        if (terms.length === 0)
+            return [];
+        const maxResults = clampPositive(opts.maxResults, DEFAULT_MAX_RESULTS);
+        const minScore = opts.minScore ?? DEFAULT_MIN_SCORE;
+        const files = await this.listCorpusFiles();
+        const hits = [];
+        for (const relPath of files) {
+            const text = await this.readForSearch(relPath);
+            if (text === undefined)
+                continue; // vanished / unreadable — skip
+            for (const chunk of splitIntoChunks(text)) {
+                const score = scoreChunk(chunk.text, terms);
+                if (score >= minScore) {
+                    hits.push({
+                        relPath,
+                        startLine: chunk.startLine,
+                        endLine: chunk.endLine,
+                        score,
+                        snippet: truncateSnippet(chunk.text.trim()),
+                    });
+                }
+            }
+        }
+        // Highest score first; ties broken by shorter snippet (more focused),
+        // then by path for determinism.
+        hits.sort((a, b) => {
+            if (b.score !== a.score)
+                return b.score - a.score;
+            if (a.snippet.length !== b.snippet.length)
+                return a.snippet.length - b.snippet.length;
+            return a.relPath.localeCompare(b.relPath);
+        });
+        // Apply BOTH caps: at most `maxResults` hits AND a total snippet-char
+        // budget so a recall can't flood the context window. Iterate the
+        // already-sorted hits and stop when either limit is reached.
+        const out = [];
+        let totalChars = 0;
+        for (const hit of hits) {
+            if (out.length >= maxResults)
+                break;
+            if (totalChars + hit.snippet.length > MAX_TOTAL_SNIPPET_CHARS && out.length > 0)
+                break;
+            out.push(hit);
+            totalChars += hit.snippet.length;
+        }
+        return out;
+    }
+    /**
+     * Read a corpus file for SEARCH with a byte cap. Files over
+     * `MAX_SEARCH_FILE_BYTES` are read head-only so an unbounded daily note
+     * can't OOM the process. Returns undefined when the file can't be read.
+     */
+    async readForSearch(relPath) {
+        const full = path.join(this.workspaceDir, relPath);
+        try {
+            const stat = await fs.stat(full);
+            if (stat.size <= MAX_SEARCH_FILE_BYTES) {
+                return await fs.readFile(full, "utf8");
+            }
+            // Oversized: read the first MAX_SEARCH_FILE_BYTES only.
+            const handle = await fs.open(full, "r");
+            try {
+                const buf = Buffer.alloc(MAX_SEARCH_FILE_BYTES);
+                const { bytesRead } = await handle.read(buf, 0, MAX_SEARCH_FILE_BYTES, 0);
+                return buf.subarray(0, bytesRead).toString("utf8");
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Bounded read of a single memory file. `relPath` must be `MEMORY.md`
+     * or a file under `memory/` — anything else throws
+     * `BrigadeMemoryPathError` (no reading arbitrary workspace files
+     * through the memory tool).
+     */
+    async read(relPath, opts = {}) {
+        const safeRel = this.assertCorpusPath(relPath);
+        const from = clampPositive(opts.from, 1);
+        const requested = clampPositive(opts.lines, DEFAULT_READ_LINES);
+        const lineBudget = Math.min(requested, MAX_READ_LINES);
+        let raw;
+        try {
+            raw = await fs.readFile(path.join(this.workspaceDir, safeRel), "utf8");
+        }
+        catch (err) {
+            const code = err.code;
+            if (code === "ENOENT") {
+                throw new BrigadeMemoryPathError(`memory file "${safeRel}" does not exist. Use recall_memory to find what's stored, ` +
+                    `or write to "memory/<today>.md" to create a note.`);
+            }
+            // EACCES / EISDIR / EBUSY / etc — report the actual problem rather
+            // than the misleading "does not exist".
+            throw new BrigadeMemoryPathError(`memory file "${safeRel}" could not be read (${code ?? "unknown error"}).`);
+        }
+        const allLines = raw.split(/\r?\n/);
+        // A file ending in a newline produces a trailing "" element from the
+        // split — drop exactly one so a 2-line "a\nb\n" reports 2 lines, not
+        // 3 (and a genuine blank last line "a\n\n" still reports 2: a + blank).
+        if (allLines.length > 1 && allLines[allLines.length - 1] === "") {
+            allLines.pop();
+        }
+        const startIdx = Math.max(0, from - 1);
+        const slice = allLines.slice(startIdx, startIdx + lineBudget);
+        const endIdx = startIdx + slice.length; // exclusive
+        const truncated = endIdx < allLines.length;
+        return {
+            relPath: safeRel,
+            text: slice.join("\n"),
+            truncated,
+            from: startIdx + 1,
+            lines: slice.length,
+            ...(truncated ? { nextFrom: endIdx + 1 } : {}),
+        };
+    }
+    async status() {
+        const files = await this.listCorpusFiles();
+        let totalBytes = 0;
+        for (const relPath of files) {
+            try {
+                const stat = await fs.stat(path.join(this.workspaceDir, relPath));
+                totalBytes += stat.size;
+            }
+            catch {
+                // skip vanished file
+            }
+        }
+        return {
+            backend: "file",
+            fileCount: files.length,
+            totalBytes,
+            root: this.workspaceDir,
+        };
+    }
+    /**
+     * List the corpus files (relative paths): MEMORY.md if present, plus
+     * every `*.md` under `memory/`. Sorted for deterministic search output.
+     */
+    async listCorpusFiles() {
+        const out = [];
+        // MEMORY.md (persona-level memory) — optional.
+        try {
+            const stat = await fs.stat(path.join(this.workspaceDir, "MEMORY.md"));
+            if (stat.isFile())
+                out.push("MEMORY.md");
+        }
+        catch {
+            // absent — fine
+        }
+        // memory/*.md daily notes.
+        const memoryDir = path.join(this.workspaceDir, "memory");
+        try {
+            const entries = await fs.readdir(memoryDir, { withFileTypes: true });
+            for (const e of entries) {
+                if (e.isFile() && e.name.toLowerCase().endsWith(".md")) {
+                    out.push(path.posix.join("memory", e.name));
+                }
+            }
+        }
+        catch {
+            // no memory dir yet — fine
+        }
+        return out.sort();
+    }
+    /**
+     * Validate + normalise a caller-supplied relPath. Accepts only
+     * `MEMORY.md` (case-insensitive) or a `*.md` directly under `memory/`.
+     * Rejects traversal, absolute paths, nested subdirs, and non-md files.
+     */
+    assertCorpusPath(relPath) {
+        const raw = (relPath ?? "").trim().replace(/\\/g, "/");
+        if (!raw) {
+            throw new BrigadeMemoryPathError("memory path is empty.");
+        }
+        if (raw.startsWith("/") || /^[a-zA-Z]:/.test(raw)) {
+            throw new BrigadeMemoryPathError(`memory path "${relPath}" must be relative (MEMORY.md or memory/<file>.md), not absolute.`);
+        }
+        if (raw.includes("..")) {
+            throw new BrigadeMemoryPathError(`memory path "${relPath}" must not contain "..".`);
+        }
+        // MEMORY.md at the workspace root.
+        if (raw.toLowerCase() === "memory.md")
+            return "MEMORY.md";
+        // memory/<name>.md — exactly one segment under memory/, must be .md.
+        const m = /^memory\/([^/]+\.md)$/i.exec(raw);
+        if (m)
+            return `memory/${m[1]}`;
+        throw new BrigadeMemoryPathError(`memory path "${relPath}" is not a memory file. Allowed: "MEMORY.md" or "memory/<name>.md".`);
+    }
+}
+/* ───────────────────────── lexical search helpers ───────────────────────── */
+/** Lowercase + split on non-word chars; drop terms shorter than 2 chars. */
+export function tokenize(text) {
+    return (text ?? "")
+        .toLowerCase()
+        .split(/[^a-z0-9]+/i)
+        .filter((t) => t.length >= 2);
+}
+/**
+ * Split a file into blank-line-separated chunks, tracking 1-based line
+ * numbers so search hits can cite where they came from. A run of one or
+ * more blank lines is the separator.
+ */
+export function splitIntoChunks(text) {
+    const lines = text.split(/\r?\n/);
+    const chunks = [];
+    let buf = [];
+    let chunkStart = 1;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? "";
+        if (line.trim() === "") {
+            if (buf.length > 0) {
+                chunks.push({ text: buf.join("\n"), startLine: chunkStart, endLine: i });
+                buf = [];
+            }
+            chunkStart = i + 2; // next non-blank line is i+2 (1-based)
+        }
+        else {
+            if (buf.length === 0)
+                chunkStart = i + 1;
+            buf.push(line);
+        }
+    }
+    if (buf.length > 0) {
+        chunks.push({ text: buf.join("\n"), startLine: chunkStart, endLine: lines.length });
+    }
+    return chunks;
+}
+/**
+ * Score a chunk by how many DISTINCT query terms it contains, plus a
+ * small bonus for total term frequency. Distinct-term coverage dominates
+ * so a chunk mentioning all query terms once beats a chunk repeating one
+ * term many times.
+ */
+export function scoreChunk(chunkText, queryTerms) {
+    if (queryTerms.length === 0)
+        return 0;
+    const chunkTokens = tokenize(chunkText);
+    if (chunkTokens.length === 0)
+        return 0;
+    const freq = new Map();
+    for (const tok of chunkTokens)
+        freq.set(tok, (freq.get(tok) ?? 0) + 1);
+    let distinct = 0;
+    let totalFreq = 0;
+    for (const term of new Set(queryTerms)) {
+        const f = freq.get(term) ?? 0;
+        if (f > 0) {
+            distinct += 1;
+            totalFreq += f;
+        }
+    }
+    // Distinct coverage is the integer part; frequency is a sub-1 tiebreak.
+    return distinct + Math.min(totalFreq, 9) / 10;
+}
+function clampPositive(value, fallback) {
+    if (value === undefined || !Number.isFinite(value) || value <= 0)
+        return fallback;
+    return Math.floor(value);
+}
+/**
+ * Cap a single snippet's length so one blank-line-free paragraph can't
+ * become a giant context dump. Truncates on a word boundary when possible
+ * and appends an ellipsis marker the model understands.
+ */
+function truncateSnippet(text) {
+    if (text.length <= MAX_SNIPPET_CHARS)
+        return text;
+    const slice = text.slice(0, MAX_SNIPPET_CHARS);
+    const lastSpace = slice.lastIndexOf(" ");
+    const cut = lastSpace > MAX_SNIPPET_CHARS * 0.8 ? slice.slice(0, lastSpace) : slice;
+    return `${cut} … [truncated; read_memory for the full text]`;
+}
+//# sourceMappingURL=storage.js.map

package/dist/agents/memory/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../../../src/agents/memory/storage.ts"],"names":[],"mappings":"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"}