causantic 0.2.0

package/dist/utils/secure-buffer.js

@@ -0,0 +1,104 @@
+/**
+ * Secure buffer utilities for handling sensitive data.
+ *
+ * Provides memory protection by zeroing buffers when done.
+ */
+/**
+ * Secure buffer that zeros memory when cleared.
+ *
+ * Use for encryption keys, passwords, and other sensitive data that
+ * should not linger in memory after use.
+ *
+ * @example
+ * ```typescript
+ * const keyBuffer = new SecureBuffer(secretKey);
+ * try {
+ *   db.pragma(`key = '${keyBuffer.toString()}'`);
+ * } finally {
+ *   keyBuffer.clear();
+ * }
+ * ```
+ */
+export class SecureBuffer {
+    buffer;
+    cleared = false;
+    constructor(data) {
+        this.buffer = Buffer.isBuffer(data) ? Buffer.from(data) : Buffer.from(data, 'utf-8');
+    }
+    /**
+     * Get the buffer contents as a string.
+     * @throws Error if buffer has been cleared
+     */
+    toString(encoding = 'utf-8') {
+        if (this.cleared) {
+            throw new Error('SecureBuffer has been cleared');
+        }
+        return this.buffer.toString(encoding);
+    }
+    /**
+     * Get a copy of the raw buffer.
+     * @throws Error if buffer has been cleared
+     */
+    toBuffer() {
+        if (this.cleared) {
+            throw new Error('SecureBuffer has been cleared');
+        }
+        return Buffer.from(this.buffer);
+    }
+    /**
+     * Check if the buffer has been cleared.
+     */
+    isCleared() {
+        return this.cleared;
+    }
+    /**
+     * Get the length of the buffer.
+     */
+    get length() {
+        return this.buffer.length;
+    }
+    /**
+     * Zero the buffer memory and mark as cleared.
+     * Safe to call multiple times.
+     */
+    clear() {
+        if (!this.cleared) {
+            // Overwrite with zeros
+            this.buffer.fill(0);
+            this.cleared = true;
+        }
+    }
+}
+/**
+ * Execute a function with a secure buffer, ensuring cleanup.
+ *
+ * @example
+ * ```typescript
+ * await withSecureBuffer(password, (buf) => {
+ *   db.pragma(`key = '${buf.toString()}'`);
+ * });
+ * // Buffer is automatically cleared
+ * ```
+ */
+export async function withSecureBuffer(data, fn) {
+    const buffer = new SecureBuffer(data);
+    try {
+        return await fn(buffer);
+    }
+    finally {
+        buffer.clear();
+    }
+}
+/**
+ * Synchronous version of withSecureBuffer.
+ */
+export function withSecureBufferSync(data, fn) {
+    const buffer = new SecureBuffer(data);
+    try {
+        return fn(buffer);
+    }
+    finally {
+        buffer.clear();
+    }
+}
+//# sourceMappingURL=secure-buffer.js.map

package/dist/utils/secure-buffer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secure-buffer.js","sourceRoot":"","sources":["../../src/utils/secure-buffer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,YAAY;IACf,MAAM,CAAS;IACf,OAAO,GAAG,KAAK,CAAC;IAExB,YAAY,IAAqB;QAC/B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACvF,CAAC;IAED;;;OAGG;IACH,QAAQ,CAAC,WAA2B,OAAO;QACzC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;QACnD,CAAC;QACD,OAAO,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACxC,CAAC;IAED;;;OAGG;IACH,QAAQ;QACN,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;QACnD,CAAC;QACD,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAClC,CAAC;IAED;;OAEG;IACH,SAAS;QACP,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED;;OAEG;IACH,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;IAC5B,CAAC;IAED;;;OAGG;IACH,KAAK;QACH,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YAClB,uBAAuB;YACvB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YACpB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACtB,CAAC;IACH,CAAC;CACF;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,IAAqB,EACrB,EAA4C;IAE5C,MAAM,MAAM,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,CAAC,MAAM,CAAC,CAAC;IAC1B,CAAC;YAAS,CAAC;QACT,MAAM,CAAC,KAAK,EAAE,CAAC;IACjB,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAClC,IAAqB,EACrB,EAA+B;IAE/B,MAAM,MAAM,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,CAAC;QACH,OAAO,EAAE,CAAC,MAAM,CAAC,CAAC;IACpB,CAAC;YAAS,CAAC;QACT,MAAM,CAAC,KAAK,EAAE,CAAC;IACjB,CAAC;AACH,CAAC"}

package/dist/utils/token-counter.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Approximate token counting.
+ *
+ * Uses a simple heuristic (~4 chars per token for English text,
+ * adjusted for code which tends to have shorter tokens).
+ * This is sufficient for chunking decisions; we don't need exact counts.
+ */
+/**
+ * Approximate token count for a string.
+ * Biased slightly high to avoid over-stuffing chunks.
+ */
+export declare function approximateTokens(text: string): number;
+//# sourceMappingURL=token-counter.d.ts.map

package/dist/utils/token-counter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-counter.d.ts","sourceRoot":"","sources":["../../src/utils/token-counter.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGtD"}

package/dist/utils/token-counter.js

@@ -0,0 +1,18 @@
+/**
+ * Approximate token counting.
+ *
+ * Uses a simple heuristic (~4 chars per token for English text,
+ * adjusted for code which tends to have shorter tokens).
+ * This is sufficient for chunking decisions; we don't need exact counts.
+ */
+const CHARS_PER_TOKEN = 3.5;
+/**
+ * Approximate token count for a string.
+ * Biased slightly high to avoid over-stuffing chunks.
+ */
+export function approximateTokens(text) {
+    if (!text)
+        return 0;
+    return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+//# sourceMappingURL=token-counter.js.map

package/dist/utils/token-counter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-counter.js","sourceRoot":"","sources":["../../src/utils/token-counter.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,eAAe,GAAG,GAAG,CAAC;AAE5B;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,IAAI,CAAC,IAAI;QAAE,OAAO,CAAC,CAAC;IACpB,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,eAAe,CAAC,CAAC;AAClD,CAAC"}

package/package.json

@@ -0,0 +1,110 @@
+{
+  "name": "causantic",
+  "version": "0.2.0",
+  "description": "Long-term memory system for Claude Code using causal graphs and vector clocks",
+  "type": "module",
+  "private": false,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Entrolution/causantic.git"
+  },
+  "bugs": "https://github.com/Entrolution/causantic/issues",
+  "homepage": "https://github.com/Entrolution/causantic#readme",
+  "keywords": [
+    "claude-code",
+    "memory",
+    "vector-clock",
+    "causal-graph",
+    "semantic-search",
+    "hdbscan",
+    "embeddings",
+    "mcp"
+  ],
+  "author": "Entrolution",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "causantic": "dist/cli/index.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./mcp": {
+      "import": "./dist/mcp/index.js",
+      "types": "./dist/mcp/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "config.schema.json",
+    "README.md",
+    "LICENSE",
+    "src/dashboard/client/package.json",
+    "src/dashboard/client/package-lock.json"
+  ],
+  "scripts": {
+    "build": "tsc && cp src/storage/schema.sql dist/storage/ && cd src/dashboard/client && npm install --ignore-scripts && npm run build",
+    "build:server": "tsc && cp src/storage/schema.sql dist/storage/",
+    "build:client": "cd src/dashboard/client && npm install --ignore-scripts && npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src/ test/",
+    "lint:fix": "eslint src/ test/ --fix",
+    "format": "prettier --write 'src/**/*.ts' 'test/**/*.ts'",
+    "format:check": "prettier --check 'src/**/*.ts' 'test/**/*.ts'",
+    "ingest": "tsx scripts/ops/ingest.ts",
+    "batch-ingest": "tsx scripts/ops/batch-ingest.ts",
+    "recall": "tsx scripts/ops/recall.ts",
+    "recluster": "tsx scripts/ops/recluster.ts",
+    "recluster-fast": "tsx scripts/ops/recluster-fast.ts",
+    "refresh-clusters": "tsx scripts/ops/refresh-clusters.ts",
+    "mcp-server": "tsx scripts/ops/mcp-server.ts",
+    "debug:forward": "tsx scripts/debug/debug-forward.ts",
+    "debug:traversal": "tsx scripts/debug/debug-traversal.ts",
+    "debug:compare": "tsx scripts/debug/compare-retrieval.ts",
+    "debug:investigate": "tsx scripts/debug/investigate-traversal.ts",
+    "verify-clocks": "tsx scripts/debug/verify-clocks.ts",
+    "experiments": "tsx scripts/experiments/run-experiments.ts",
+    "topic-continuity": "tsx scripts/experiments/run-topic-continuity.ts",
+    "edge-decay-sim": "tsx scripts/experiments/run-edge-decay-sim.ts",
+    "edge-decay-experiments": "tsx scripts/experiments/run-edge-decay-experiments.ts",
+    "cluster-threshold": "tsx scripts/experiments/run-cluster-threshold.ts",
+    "hold-period-sweep": "tsx scripts/experiments/run-hold-period-sweep.ts",
+    "noncoding-validation": "tsx scripts/experiments/run-noncoding-validation.ts",
+    "vector-decay-sweep": "tsx scripts/experiments/run-vector-decay-sweep.ts",
+    "min-weight-sweep": "tsx scripts/experiments/sweep-min-weight.ts",
+    "depth-sweep": "tsx scripts/experiments/sweep-depth.ts",
+    "cross-project": "tsx scripts/experiments/cross-project-experiment.ts",
+    "hop-decay-shapes": "tsx src/eval/experiments/vector-decay-shapes/run-experiment.ts",
+    "build-corpus": "tsx scripts/build/build-corpus.ts",
+    "benchmark": "tsx scripts/build/run-benchmark.ts",
+    "benchmark:hdbscan": "tsx scripts/benchmarks/hdbscan-benchmark.ts",
+    "docs:build": "typedoc --out docs/api src/index.ts --name 'Causantic API' --readme none --excludePrivate --excludeInternal"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.74.0",
+    "@huggingface/transformers": "^3.4.1",
+    "better-sqlite3-multiple-ciphers": "^12.6.2",
+    "express": "^5.2.1",
+    "onnxruntime-node": "^1.24.1"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.2.3",
+    "@typescript-eslint/eslint-plugin": "^8.55.0",
+    "@typescript-eslint/parser": "^8.55.0",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.8.1",
+    "tsx": "^4.19.0",
+    "typedoc": "^0.28.16",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}