brainbank 0.1.0

package/dist/types-Da_zLLOl.d.ts

@@ -0,0 +1,474 @@
+import BetterSqlite3 from 'better-sqlite3';
+
+/**
+ * BrainBank — Database
+ *
+ * Thin wrapper over better-sqlite3.
+ * Handles WAL mode, directory creation, schema init, and transactions.
+ */
+
+declare class Database {
+    readonly db: BetterSqlite3.Database;
+    constructor(dbPath: string);
+    /**
+     * Run a function inside a transaction.
+     * Auto-commits on success, auto-rollbacks on error.
+     */
+    transaction<T>(fn: () => T): T;
+    /**
+     * Run a prepared statement on multiple rows.
+     * Wraps in a single transaction for performance.
+     */
+    batch<T extends any[]>(sql: string, rows: T[]): void;
+    /** Prepare a reusable statement. */
+    prepare(sql: string): BetterSqlite3.Statement;
+    /** Execute raw SQL (no results). */
+    exec(sql: string): void;
+    /** Close the database. */
+    close(): void;
+}
+
+/**
+ * BrainBank — Type Definitions
+ *
+ * All interfaces and types for the semantic knowledge bank.
+ */
+interface BrainBankConfig {
+    /** Root path of the repository to index. Default: '.' */
+    repoPath?: string;
+    /** SQLite database path. Default: '.brainbank/brainbank.db' */
+    dbPath?: string;
+    /** Max git commits to index. Default: 500 */
+    gitDepth?: number;
+    /** Max file size in bytes to index. Default: 512_000 (500KB) */
+    maxFileSize?: number;
+    /** Max diff bytes per commit. Default: 8192 */
+    maxDiffBytes?: number;
+    /** HNSW M parameter (connections per node). Default: 16 */
+    hnswM?: number;
+    /** HNSW efConstruction (build-time candidates). Default: 200 */
+    hnswEfConstruction?: number;
+    /** HNSW efSearch (query-time candidates). Default: 50 */
+    hnswEfSearch?: number;
+    /** Embedding dimensions. Default: 384 */
+    embeddingDims?: number;
+    /** Max HNSW elements. Default: 2_000_000 */
+    maxElements?: number;
+    /** Custom embedding provider (default: local WASM model) */
+    embeddingProvider?: EmbeddingProvider;
+    /** Optional reranker for improved search quality */
+    reranker?: Reranker;
+}
+interface ResolvedConfig {
+    repoPath: string;
+    dbPath: string;
+    gitDepth: number;
+    maxFileSize: number;
+    maxDiffBytes: number;
+    hnswM: number;
+    hnswEfConstruction: number;
+    hnswEfSearch: number;
+    embeddingDims: number;
+    maxElements: number;
+    embeddingProvider?: EmbeddingProvider;
+    reranker?: Reranker;
+}
+interface EmbeddingProvider {
+    /** Vector dimensions produced by this provider. */
+    readonly dims: number;
+    /** Embed a single text string. */
+    embed(text: string): Promise<Float32Array>;
+    /** Embed multiple texts (batch). */
+    embedBatch(texts: string[]): Promise<Float32Array[]>;
+    /** Release resources. */
+    close(): Promise<void>;
+}
+interface Reranker {
+    /**
+     * Score each document's relevance to the query.
+     * @param query - The search query
+     * @param documents - Document contents to rank
+     * @returns Relevance scores (0.0 - 1.0) in same order as documents
+     */
+    rank(query: string, documents: string[]): Promise<number[]>;
+    /** Release resources (e.g. unload model). */
+    close?(): Promise<void>;
+}
+interface SearchHit {
+    id: number;
+    score: number;
+}
+interface VectorIndex {
+    /** Initialize the index. Must be called before add/search. */
+    init(): Promise<this>;
+    /** Add a vector with an integer ID. */
+    add(vector: Float32Array, id: number): void;
+    /** Search for k nearest neighbors. */
+    search(query: Float32Array, k: number): SearchHit[];
+    /** Number of vectors in the index. */
+    readonly size: number;
+}
+interface CodeChunk {
+    /** Auto-incremented DB id (set after insert) */
+    id?: number;
+    /** Relative file path from repo root */
+    filePath: string;
+    /** Chunk type: 'file' | 'function' | 'class' | 'block' */
+    chunkType: string;
+    /** Function/class name (if detected) */
+    name?: string;
+    /** Start line (1-indexed) */
+    startLine: number;
+    /** End line (1-indexed, inclusive) */
+    endLine: number;
+    /** Raw content of the chunk */
+    content: string;
+    /** Language identifier */
+    language: string;
+}
+interface GitCommitRecord {
+    id?: number;
+    hash: string;
+    shortHash: string;
+    message: string;
+    author: string;
+    date: string;
+    timestamp: number;
+    filesChanged: string[];
+    diff?: string;
+    additions: number;
+    deletions: number;
+    isMerge: boolean;
+}
+interface MemoryPattern {
+    id?: number;
+    /** Category (e.g. 'api', 'refactor', 'debug') */
+    taskType: string;
+    /** What was the task */
+    task: string;
+    /** How it was approached */
+    approach: string;
+    /** What happened */
+    outcome?: string;
+    /** 0.0 – 1.0 */
+    successRate: number;
+    /** Lessons learned */
+    critique?: string;
+    /** Tokens consumed (optional tracking) */
+    tokensUsed?: number;
+    /** Latency in ms (optional tracking) */
+    latencyMs?: number;
+}
+interface DistilledStrategy {
+    taskType: string;
+    strategy: string;
+    confidence: number;
+    updatedAt: number;
+}
+type SearchResultType = 'code' | 'commit' | 'pattern' | 'document' | 'collection';
+interface SearchResult {
+    type: SearchResultType;
+    score: number;
+    /** File path (for code results) or document path */
+    filePath?: string;
+    /** Content / text */
+    content: string;
+    /** Context description (for document results) */
+    context?: string;
+    /** Extra metadata depending on type */
+    metadata: Record<string, any>;
+}
+interface ContextOptions {
+    /** Max code chunks to include. Default: 6 */
+    codeResults?: number;
+    /** Max git commits to include. Default: 5 */
+    gitResults?: number;
+    /** Max memory patterns to include. Default: 4 */
+    memoryResults?: number;
+    /** Files the agent is about to modify (improves co-edit suggestions) */
+    affectedFiles?: string[];
+    /** Minimum similarity score threshold. Default: 0.25 */
+    minScore?: number;
+    /** Use MMR for diversity. Default: true */
+    useMMR?: boolean;
+    /** MMR lambda (0 = diversity, 1 = relevance). Default: 0.7 */
+    mmrLambda?: number;
+}
+interface DocumentCollection {
+    /** Collection name (e.g. 'notes', 'docs') */
+    name: string;
+    /** Directory path to index */
+    path: string;
+    /** Glob pattern for files (default: all markdown) */
+    pattern?: string;
+    /** Glob patterns to ignore */
+    ignore?: string[];
+    /** Context description for this collection */
+    context?: string;
+}
+interface DocChunk {
+    id?: number;
+    /** Collection name */
+    collection: string;
+    /** Relative file path within the collection */
+    filePath: string;
+    /** Document title (first heading or filename) */
+    title: string;
+    /** Chunk content */
+    content: string;
+    /** Chunk sequence within the document (0, 1, 2...) */
+    seq: number;
+    /** Character position in original document */
+    pos: number;
+    /** Content hash for incremental updates */
+    contentHash: string;
+}
+interface IndexStats {
+    code?: {
+        files: number;
+        chunks: number;
+        hnswSize: number;
+    };
+    git?: {
+        commits: number;
+        filesTracked: number;
+        coEdits: number;
+        hnswSize: number;
+    };
+    memory?: {
+        patterns: number;
+        avgSuccess: number;
+        hnswSize: number;
+    };
+    documents?: {
+        collections: number;
+        documents: number;
+        chunks: number;
+        hnswSize: number;
+    };
+    notes?: {
+        total: number;
+        short: number;
+        long: number;
+    };
+}
+type ProgressCallback = (file: string, current: number, total: number) => void;
+interface IndexResult {
+    indexed: number;
+    skipped: number;
+    chunks?: number;
+}
+interface CoEditSuggestion {
+    file: string;
+    count: number;
+}
+
+/**
+ * BrainBank — HNSW Vector Index
+ *
+ * Wraps hnswlib-node for O(log n) approximate nearest neighbor search.
+ * M=16 connections, ef=200 construction, ef=50 search by default.
+ * 150x faster than brute force at 1M vectors.
+ */
+
+declare class HNSWIndex implements VectorIndex {
+    private _dims;
+    private _maxElements;
+    private _M;
+    private _efConstruction;
+    private _efSearch;
+    private _index;
+    private _count;
+    constructor(_dims: number, _maxElements?: number, _M?: number, _efConstruction?: number, _efSearch?: number);
+    /**
+     * Initialize the HNSW index.
+     * Must be called before add/search.
+     */
+    init(): Promise<this>;
+    /**
+     * Add a vector with an integer ID.
+     * The vector should be pre-normalized for cosine distance.
+     */
+    add(vector: Float32Array, id: number): void;
+    /**
+     * Search for the k nearest neighbors.
+     * Returns results sorted by score (highest first).
+     * Score is 1 - cosine_distance (1.0 = identical).
+     */
+    search(query: Float32Array, k: number): SearchHit[];
+    /** Number of vectors in the index. */
+    get size(): number;
+}
+
+/**
+ * BrainBank — Collection
+ *
+ * Universal key-value store with vector + BM25 hybrid search.
+ * The foundation primitive — store anything, search semantically.
+ *
+ *   const errors = brain.collection('debug_errors');
+ *   await errors.add('Fixed null check in api handler', { file: 'api.ts' });
+ *   const hits = await errors.search('null pointer');
+ */
+
+interface CollectionItem {
+    id: number;
+    collection: string;
+    content: string;
+    metadata: Record<string, any>;
+    tags: string[];
+    createdAt: number;
+    expiresAt?: number;
+    score?: number;
+}
+interface CollectionSearchOptions {
+    /** Max results. Default: 5 */
+    k?: number;
+    /** Search mode. Default: 'hybrid' */
+    mode?: 'hybrid' | 'vector' | 'keyword';
+    /** Minimum score threshold. Default: 0.15 */
+    minScore?: number;
+    /** Filter by tags (item must have ALL specified tags). */
+    tags?: string[];
+}
+interface CollectionAddOptions {
+    /** Metadata key-value pairs. */
+    metadata?: Record<string, any>;
+    /** Tags for filtering. */
+    tags?: string[];
+    /** Time-to-live duration string (e.g. '7d', '24h', '30m'). */
+    ttl?: string;
+}
+declare class Collection {
+    private _name;
+    private _db;
+    private _embedding;
+    private _hnsw;
+    private _vecs;
+    private _reranker?;
+    constructor(_name: string, _db: Database, _embedding: EmbeddingProvider, _hnsw: HNSWIndex, _vecs: Map<number, Float32Array>, _reranker?: Reranker | undefined);
+    /** Collection name. */
+    get name(): string;
+    /** Add an item. Returns its ID. */
+    add(content: string, options?: CollectionAddOptions | Record<string, any>): Promise<number>;
+    /** Add multiple items. Returns their IDs. */
+    addMany(items: {
+        content: string;
+        metadata?: Record<string, any>;
+        tags?: string[];
+        ttl?: string;
+    }[]): Promise<number[]>;
+    /** Search this collection. */
+    search(query: string, options?: CollectionSearchOptions): Promise<CollectionItem[]>;
+    /** List items (newest first). */
+    list(options?: {
+        limit?: number;
+        offset?: number;
+        tags?: string[];
+    }): CollectionItem[];
+    /** Count items in this collection. */
+    count(): number;
+    /** Keep only the N most recent items, remove the rest. */
+    trim(options: {
+        keep: number;
+    }): Promise<{
+        removed: number;
+    }>;
+    /** Remove items older than a duration string (e.g. '30d', '12h'). */
+    prune(options: {
+        olderThan: string;
+    }): Promise<{
+        removed: number;
+    }>;
+    /** Remove a specific item by ID. */
+    remove(id: number): void;
+    /** Clear all items in this collection. */
+    clear(): void;
+    private _removeById;
+    private _searchVector;
+    private _searchBM25;
+    private _rowToItem;
+    /** Filter results by tags (item must have ALL specified tags). */
+    private _filterByTags;
+    /** Remove expired items (TTL). Called automatically on search/list. */
+    private _pruneExpired;
+}
+
+/**
+ * BrainBank — Indexer System
+ *
+ * Indexers are pluggable strategies that scan external data sources
+ * and push content into BrainBank. Built-in indexers handle code,
+ * git, and docs. Third-party frameworks (LangChain, etc.)
+ * can implement custom indexers.
+ *
+ *   import { BrainBank } from 'brainbank';
+ *   import { code } from 'brainbank/indexers/code';
+ *
+ *   const brain = new BrainBank()
+ *     .use(code({ repoPath: '.' }));
+ */
+
+interface IndexerContext {
+    /** SQLite database (shared across all indexers). */
+    db: Database;
+    /** Embedding provider (shared). */
+    embedding: EmbeddingProvider;
+    /** Resolved BrainBank config. */
+    config: ResolvedConfig;
+    /** Create and initialize an HNSW index. */
+    createHnsw(maxElements?: number): Promise<HNSWIndex>;
+    /** Load existing vectors from a SQLite vectors table into an HNSW index + cache. */
+    loadVectors(table: string, idCol: string, hnsw: HNSWIndex, cache: Map<number, Float32Array>): void;
+    /** Get or create a shared HNSW index by type (e.g. 'code', 'git'). For multi-repo support. */
+    getOrCreateSharedHnsw(type: string, maxElements?: number): Promise<{
+        hnsw: HNSWIndex;
+        vecCache: Map<number, Float32Array>;
+        isNew: boolean;
+    }>;
+    /** Get or create a dynamic collection. */
+    collection(name: string): Collection;
+}
+interface Indexer {
+    /** Unique indexer name (e.g. 'code', 'git', 'docs'). */
+    readonly name: string;
+    /** Initialize the indexer (create HNSW, load vectors, etc.). */
+    initialize(ctx: IndexerContext): Promise<void>;
+    /** Index content. Implemented by code and git indexers. */
+    index?(options?: any): Promise<any>;
+    /** Search indexed content. Implemented by docs indexer. */
+    search?(query: string, options?: any): Promise<any[]>;
+    /** Register a document collection. */
+    addCollection?(collection: any): void;
+    /** Remove a collection. */
+    removeCollection?(name: string): void;
+    /** List registered collections. */
+    listCollections?(): any[];
+    /** Index all or specific collections. */
+    indexCollections?(options?: any): Promise<any>;
+    /** Add context description for a collection path. */
+    addContext?(collection: string, path: string, context: string): void;
+    /** Remove context for a collection path. */
+    removeContext?(collection: string, path: string): void;
+    /** List all context entries. */
+    listContexts?(): any[];
+    /**
+     * Called by watch mode when a file changes.
+     * Return true if this indexer handled the change.
+     * If not implemented, watch will fall back to brain.index().
+     */
+    onFileChange?(filePath: string, event: 'create' | 'update' | 'delete'): Promise<boolean>;
+    /**
+     * Glob patterns this indexer watches.
+     * If not set, defaults to all supported code extensions.
+     */
+    watchPatterns?(): string[];
+    /** Return stats for this indexer. */
+    stats?(): Record<string, any>;
+    /** Clean up resources. */
+    close?(): void;
+}
+type BrainBankModule = Indexer;
+type ModuleContext = IndexerContext;
+
+export { type BrainBankModule as B, Collection as C, type DocumentCollection as D, type EmbeddingProvider as E, type GitCommitRecord as G, HNSWIndex as H, type Indexer as I, type MemoryPattern as M, type ProgressCallback as P, type ResolvedConfig as R, type SearchResult as S, type VectorIndex as V, type BrainBankConfig as a, type IndexResult as b, type ContextOptions as c, type CoEditSuggestion as d, type IndexStats as e, type SearchHit as f, type CodeChunk as g, Database as h, type Reranker as i, type CollectionAddOptions as j, type CollectionItem as k, type CollectionSearchOptions as l, type DistilledStrategy as m, type DocChunk as n, type IndexerContext as o, type ModuleContext as p, type SearchResultType as q };

package/package.json

@@ -0,0 +1,91 @@
+{
+    "name": "brainbank",
+    "version": "0.1.0",
+    "description": "Pluggable semantic memory for AI agents — hybrid search (vector + BM25) in a single SQLite file. Built-in code, git, and docs indexers. Bring your own.",
+    "type": "module",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "bin": {
+        "brainbank": "./dist/cli.js"
+    },
+    "exports": {
+        ".": {
+            "import": "./dist/index.js",
+            "types": "./dist/index.d.ts"
+        },
+        "./code": {
+            "import": "./dist/code.js",
+            "types": "./dist/code.d.ts"
+        },
+        "./git": {
+            "import": "./dist/git.js",
+            "types": "./dist/git.d.ts"
+        },
+        "./docs": {
+            "import": "./dist/docs.js",
+            "types": "./dist/docs.d.ts"
+        },
+        "./notes": {
+            "import": "./dist/notes.js",
+            "types": "./dist/notes.d.ts"
+        },
+        "./memory": {
+            "import": "./dist/memory.js",
+            "types": "./dist/memory.d.ts"
+        }
+    },
+    "files": [
+        "dist/",
+        "bin/",
+        "LICENSE",
+        "README.md",
+        "assets/"
+    ],
+    "scripts": {
+        "build": "tsup && npm run build --workspaces --if-present",
+        "build:core": "tsup",
+        "prepublishOnly": "npm run build:core",
+        "test": "node --import tsx test/run.ts",
+        "test:integration": "node --import tsx test/run.ts --integration",
+        "test:verbose": "node --import tsx test/run.ts --verbose",
+        "dev": "tsx src/integrations/cli.ts"
+    },
+    "engines": {
+        "node": ">=18"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/pinecall/brainbank.git"
+    },
+    "keywords": [
+        "ai",
+        "agent",
+        "semantic-memory",
+        "vector-search",
+        "knowledge-base",
+        "embeddings",
+        "hnsw",
+        "typescript"
+    ],
+    "author": "Bernardo Castro <bernardo@pinecall.io>",
+    "license": "MIT",
+    "dependencies": {
+        "better-sqlite3": "^11.8.1",
+        "hnswlib-node": "^3.0.0"
+    },
+    "optionalDependencies": {
+        "@xenova/transformers": "^2.17.2",
+        "simple-git": "^3.27.0"
+    },
+    "devDependencies": {
+        "@ai-sdk/openai": "^3.0.47",
+        "@langchain/core": "^1.1.35",
+        "@langchain/openai": "^1.3.0",
+        "@types/better-sqlite3": "^7.6.13",
+        "@types/node": "^22.0.0",
+        "ai": "^6.0.134",
+        "tsup": "^8.4.0",
+        "tsx": "^4.19.0",
+        "typescript": "^5.7.0"
+    }
+}