audrey 0.3.0 → 0.3.2

package/src/prompts.js

@@ -1,5 +1,9 @@
 import { safeJsonParse } from './utils.js';
 
+/**
+ * @param {Object[]} episodes
+ * @returns {import('./llm.js').ChatMessage[]}
+ */
 export function buildPrincipleExtractionPrompt(episodes) {
   const episodeList = episodes.map((ep, i) => {
     const tags = safeJsonParse(ep.tags, []);
@@ -36,6 +40,11 @@ Rules:
   ];
 }
 
+/**
+ * @param {string} newContent
+ * @param {string} existingContent
+ * @returns {import('./llm.js').ChatMessage[]}
+ */
 export function buildContradictionDetectionPrompt(newContent, existingContent) {
   return [
     {
@@ -67,6 +76,11 @@ EXISTING CLAIM: ${existingContent}`,
   ];
 }
 
+/**
+ * @param {{ content: string, source: string }} cause
+ * @param {{ content: string, source: string }} effect
+ * @returns {import('./llm.js').ChatMessage[]}
+ */
 export function buildCausalArticulationPrompt(cause, effect) {
   return [
     {
@@ -100,6 +114,12 @@ EFFECT: ${effect.content} (source: ${effect.source})`,
   ];
 }
 
+/**
+ * @param {string} claimA
+ * @param {string} claimB
+ * @param {string} [context]
+ * @returns {import('./llm.js').ChatMessage[]}
+ */
 export function buildContextResolutionPrompt(claimA, claimB, context) {
   const contextSection = context
     ? `\n\nADDITIONAL CONTEXT: ${context}`

package/src/recall.js

@@ -190,6 +190,13 @@ function knnProcedural(db, queryBuffer, candidateK, now, minConfidence, includeP
   return { results, matchedIds };
 }
 
+/**
+ * @param {import('better-sqlite3').Database} db
+ * @param {import('./embedding.js').EmbeddingProvider} embeddingProvider
+ * @param {string} query
+ * @param {{ minConfidence?: number, types?: string[], limit?: number, includeProvenance?: boolean, includeDormant?: boolean }} [options]
+ * @returns {AsyncGenerator<{ id: string, content: string, type: string, confidence: number, score: number, source: string, createdAt: string }>}
+ */
 export async function* recallStream(db, embeddingProvider, query, options = {}) {
   const {
     minConfidence = 0,
@@ -251,6 +258,13 @@ export async function* recallStream(db, embeddingProvider, query, options = {})
   }
 }
 
+/**
+ * @param {import('better-sqlite3').Database} db
+ * @param {import('./embedding.js').EmbeddingProvider} embeddingProvider
+ * @param {string} query
+ * @param {{ minConfidence?: number, types?: string[], limit?: number, includeProvenance?: boolean, includeDormant?: boolean }} [options]
+ * @returns {Promise<Array<{ id: string, content: string, type: string, confidence: number, score: number, source: string, createdAt: string }>>}
+ */
 export async function recall(db, embeddingProvider, query, options = {}) {
   const results = [];
   for await (const entry of recallStream(db, embeddingProvider, query, options)) {

package/src/rollback.js

@@ -1,5 +1,9 @@
 import { safeJsonParse } from './utils.js';
 
+/**
+ * @param {import('better-sqlite3').Database} db
+ * @returns {Array<{ id: string, checkpoint_cursor: string|null, input_episode_ids: string, output_memory_ids: string, started_at: string, completed_at: string|null, status: string }>}
+ */
 export function getConsolidationHistory(db) {
   return db.prepare(`
     SELECT id, checkpoint_cursor, input_episode_ids, output_memory_ids,
@@ -8,6 +12,11 @@ export function getConsolidationHistory(db) {
   `).all();
 }
 
+/**
+ * @param {import('better-sqlite3').Database} db
+ * @param {string} runId
+ * @returns {{ rolledBackMemories: number, restoredEpisodes: number }}
+ */
 export function rollbackConsolidation(db, runId) {
   const run = db.prepare('SELECT * FROM consolidation_runs WHERE id = ?').get(runId);
   if (!run) throw new Error(`Consolidation run not found: ${runId}`);

package/src/ulid.js

@@ -1,10 +1,17 @@
-import { ulid } from 'ulid';
+import { monotonicFactory } from 'ulid';
 import { createHash } from 'node:crypto';
 
+const monotonic = monotonicFactory();
+
+/** @returns {string} */
 export function generateId() {
-  return ulid();
+  return monotonic();
 }
 
+/**
+ * @param {...*} parts
+ * @returns {string}
+ */
 export function generateDeterministicId(...parts) {
   const input = JSON.stringify(parts);
   return createHash('sha256').update(input).digest('hex').slice(0, 26);

package/src/utils.js

@@ -1,3 +1,9 @@
+/**
+ * @param {Buffer} bufA
+ * @param {Buffer} bufB
+ * @param {import('./embedding.js').EmbeddingProvider} provider
+ * @returns {number}
+ */
 export function cosineSimilarity(bufA, bufB, provider) {
   const a = provider.bufferToVector(bufA);
   const b = provider.bufferToVector(bufB);
@@ -11,10 +17,20 @@ export function cosineSimilarity(bufA, bufB, provider) {
   return mag === 0 ? 0 : dot / mag;
 }
 
+/**
+ * @param {string} dateStr
+ * @param {Date} now
+ * @returns {number}
+ */
 export function daysBetween(dateStr, now) {
   return Math.max(0, (now.getTime() - new Date(dateStr).getTime()) / (1000 * 60 * 60 * 24));
 }
 
+/**
+ * @param {string | null | undefined} str
+ * @param {*} [fallback=null]
+ * @returns {*}
+ */
 export function safeJsonParse(str, fallback = null) {
   if (!str) return fallback;
   try { return JSON.parse(str); }

package/src/validate.js

@@ -5,6 +5,13 @@ import { buildContradictionDetectionPrompt } from './prompts.js';
 const REINFORCEMENT_THRESHOLD = 0.85;
 const CONTRADICTION_THRESHOLD = 0.60;
 
+/**
+ * @param {import('better-sqlite3').Database} db
+ * @param {import('./embedding.js').EmbeddingProvider} embeddingProvider
+ * @param {{ id: string, content: string, source: string }} episode
+ * @param {{ threshold?: number, contradictionThreshold?: number, llmProvider?: { json: (messages: any) => Promise<any> } }} [options]
+ * @returns {Promise<{ action: string, semanticId?: string, similarity?: number, contradictionId?: string, resolution?: string }>}
+ */
 export async function validateMemory(db, embeddingProvider, episode, options = {}) {
   const {
     threshold = REINFORCEMENT_THRESHOLD,
@@ -121,6 +128,15 @@ function computeSourceDiversity(db, evidenceIds, currentEpisode) {
   return sourceTypes.size;
 }
 
+/**
+ * @param {import('better-sqlite3').Database} db
+ * @param {string} claimAId
+ * @param {string} claimAType
+ * @param {string} claimBId
+ * @param {string} claimBType
+ * @param {object|null} resolution
+ * @returns {string}
+ */
 export function createContradiction(db, claimAId, claimAType, claimBId, claimBType, resolution) {
   const id = generateId();
   const now = new Date().toISOString();
@@ -138,6 +154,12 @@ export function createContradiction(db, claimAId, claimAType, claimBId, claimBTy
   return id;
 }
 
+/**
+ * @param {import('better-sqlite3').Database} db
+ * @param {string} contradictionId
+ * @param {string} newEvidenceId
+ * @returns {void}
+ */
 export function reopenContradiction(db, contradictionId, newEvidenceId) {
   const now = new Date().toISOString();
   db.prepare(`

package/mcp-server/register.sh

@@ -1,30 +0,0 @@
-#!/usr/bin/env bash
-# Register Audrey MCP server with Claude Code
-# Usage: bash mcp-server/register.sh [--openai] [--anthropic]
-
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-SERVER_PATH="$SCRIPT_DIR/index.js"
-
-ARGS="--transport stdio --scope user"
-ENV_ARGS=""
-
-ENV_ARGS="$ENV_ARGS --env AUDREY_DATA_DIR=$HOME/.audrey/data"
-
-if [[ "$*" == *"--openai"* ]]; then
-  ENV_ARGS="$ENV_ARGS --env AUDREY_EMBEDDING_PROVIDER=openai --env AUDREY_EMBEDDING_DIMENSIONS=1536"
-  [ -n "$OPENAI_API_KEY" ] && ENV_ARGS="$ENV_ARGS --env OPENAI_API_KEY=$OPENAI_API_KEY"
-else
-  ENV_ARGS="$ENV_ARGS --env AUDREY_EMBEDDING_PROVIDER=mock --env AUDREY_EMBEDDING_DIMENSIONS=8"
-fi
-
-if [[ "$*" == *"--anthropic"* ]]; then
-  ENV_ARGS="$ENV_ARGS --env AUDREY_LLM_PROVIDER=anthropic"
-  [ -n "$ANTHROPIC_API_KEY" ] && ENV_ARGS="$ENV_ARGS --env ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY"
-fi
-
-echo "Registering Audrey MCP server..."
-echo "  Server: $SERVER_PATH"
-
-claude mcp add $ARGS $ENV_ARGS audrey-memory -- node "$SERVER_PATH"
-
-echo "Done. Run 'claude mcp list' to verify."