@usejarvis/brain 0.1.0

package/src/vault/index.ts

@@ -0,0 +1,87 @@
+/**
+ * Vault Module - Data Access Layer for J.A.R.V.I.S. Knowledge Graph
+ *
+ * This module provides CRUD operations for all core data types in the knowledge graph:
+ * - Entities: People, projects, tools, places, concepts, events
+ * - Facts: Atomic pieces of knowledge with confidence scores
+ * - Relationships: Typed edges between entities
+ * - Commitments: Promises and tasks the AI needs to fulfill
+ * - Observations: Raw events from the observation layer
+ * - Vectors: Embeddings for semantic search
+ *
+ * All modules use Bun's SQLite API and handle JSON serialization automatically.
+ */
+
+// Re-export schema utilities
+export { initDatabase, getDb, closeDb, generateId } from './schema.ts';
+
+// Re-export entities module
+export type { Entity, EntityType } from './entities.ts';
+export {
+  createEntity,
+  getEntity,
+  findEntities,
+  updateEntity,
+  deleteEntity,
+  searchEntitiesByName,
+} from './entities.ts';
+
+// Re-export facts module
+export type { Fact } from './facts.ts';
+export {
+  createFact,
+  getFact,
+  findFacts,
+  queryFact,
+  updateFact,
+  deleteFact,
+  verifyFact,
+} from './facts.ts';
+
+// Re-export relationships module
+export type { Relationship } from './relationships.ts';
+export {
+  createRelationship,
+  getRelationship,
+  findRelationships,
+  getEntityRelationships,
+  deleteRelationship,
+} from './relationships.ts';
+
+// Re-export commitments module
+export type { Commitment, CommitmentPriority, CommitmentStatus, RetryPolicy } from './commitments.ts';
+export {
+  createCommitment,
+  getCommitment,
+  findCommitments,
+  getUpcoming,
+  completeCommitment,
+  failCommitment,
+  escalateCommitment,
+  getDueCommitments,
+} from './commitments.ts';
+
+// Re-export observations module
+export type { Observation, ObservationType } from './observations.ts';
+export {
+  createObservation,
+  getUnprocessed,
+  markProcessed,
+  getRecentObservations,
+} from './observations.ts';
+
+// Re-export vectors module
+export type { VectorRecord } from './vectors.ts';
+export {
+  storeVector,
+  findSimilar,
+  deleteVectors,
+} from './vectors.ts';
+
+// Re-export extractor module
+export type { ExtractionResult } from './extractor.ts';
+export {
+  buildExtractionPrompt,
+  parseExtractionResponse,
+  extractAndStore,
+} from './extractor.ts';

package/src/vault/keychain.ts

@@ -0,0 +1,99 @@
+/**
+ * Encrypted secrets store for JARVIS.
+ *
+ * Stores secrets in an AES-256-GCM encrypted file (~/.jarvis/.secrets.enc)
+ * with a random key stored in ~/.jarvis/.secrets.key (chmod 600).
+ *
+ * This avoids depending on OS keychain daemons (which are unreliable on WSL2).
+ */
+
+import { randomBytes, createCipheriv, createDecipheriv } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+const JARVIS_DIR = join(homedir(), '.jarvis');
+const KEY_PATH = join(JARVIS_DIR, '.secrets.key');
+const SECRETS_PATH = join(JARVIS_DIR, '.secrets.enc');
+const ALGORITHM = 'aes-256-gcm';
+const IV_LENGTH = 12;
+const TAG_LENGTH = 16;
+
+function ensureDir(): void {
+  if (!existsSync(JARVIS_DIR)) {
+    mkdirSync(JARVIS_DIR, { recursive: true });
+  }
+}
+
+function getOrCreateKey(): Buffer {
+  ensureDir();
+  if (existsSync(KEY_PATH)) {
+    const hex = readFileSync(KEY_PATH, 'utf-8').trim();
+    return Buffer.from(hex, 'hex');
+  }
+  const key = randomBytes(32);
+  writeFileSync(KEY_PATH, key.toString('hex'), { mode: 0o600 });
+  try { chmodSync(KEY_PATH, 0o600); } catch {}
+  return key;
+}
+
+function encrypt(key: Buffer, plaintext: string): Buffer {
+  const iv = randomBytes(IV_LENGTH);
+  const cipher = createCipheriv(ALGORITHM, key, iv);
+  const encrypted = Buffer.concat([cipher.update(plaintext, 'utf-8'), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return Buffer.concat([iv, tag, encrypted]);
+}
+
+function decrypt(key: Buffer, data: Buffer): string {
+  const iv = data.subarray(0, IV_LENGTH);
+  const tag = data.subarray(IV_LENGTH, IV_LENGTH + TAG_LENGTH);
+  const encrypted = data.subarray(IV_LENGTH + TAG_LENGTH);
+  const decipher = createDecipheriv(ALGORITHM, key, iv);
+  decipher.setAuthTag(tag);
+  return Buffer.concat([decipher.update(encrypted), decipher.final()]).toString('utf-8');
+}
+
+function loadSecrets(): Record<string, string> {
+  if (!existsSync(SECRETS_PATH)) return {};
+  try {
+    const key = getOrCreateKey();
+    const raw = readFileSync(SECRETS_PATH);
+    const json = decrypt(key, raw);
+    return JSON.parse(json);
+  } catch (err) {
+    console.warn('[Keychain] Failed to decrypt secrets file, starting fresh:', err);
+    return {};
+  }
+}
+
+function saveSecrets(secrets: Record<string, string>): void {
+  ensureDir();
+  const key = getOrCreateKey();
+  const json = JSON.stringify(secrets);
+  const encrypted = encrypt(key, json);
+  writeFileSync(SECRETS_PATH, encrypted, { mode: 0o600 });
+  try { chmodSync(SECRETS_PATH, 0o600); } catch {}
+}
+
+export function getSecret(name: string): string | null {
+  const secrets = loadSecrets();
+  return secrets[name] ?? null;
+}
+
+export function setSecret(name: string, value: string): void {
+  const secrets = loadSecrets();
+  secrets[name] = value;
+  saveSecrets(secrets);
+}
+
+export function deleteSecret(name: string): void {
+  const secrets = loadSecrets();
+  delete secrets[name];
+  saveSecrets(secrets);
+}
+
+export function hasSecret(name: string): boolean {
+  const secrets = loadSecrets();
+  return name in secrets;
+}

package/src/vault/observations.ts

@@ -0,0 +1,115 @@
+import { getDb, generateId } from './schema.ts';
+
+export type ObservationType =
+  | 'file_change'
+  | 'notification'
+  | 'clipboard'
+  | 'app_activity'
+  | 'calendar'
+  | 'email'
+  | 'browser'
+  | 'process'
+  | 'screen_capture';
+
+export type Observation = {
+  id: string;
+  type: ObservationType;
+  data: Record<string, unknown>;
+  processed: boolean;
+  created_at: number;
+};
+
+type ObservationRow = {
+  id: string;
+  type: ObservationType;
+  data: string;
+  processed: number;
+  created_at: number;
+};
+
+/**
+ * Parse observation row from database, deserializing JSON fields
+ */
+function parseObservation(row: ObservationRow): Observation {
+  return {
+    id: row.id,
+    type: row.type,
+    data: JSON.parse(row.data),
+    processed: row.processed === 1,
+    created_at: row.created_at,
+  };
+}
+
+/**
+ * Create a new observation
+ */
+export function createObservation(
+  type: ObservationType,
+  data: Record<string, unknown>
+): Observation {
+  const db = getDb();
+  const id = generateId();
+  const now = Date.now();
+
+  const stmt = db.prepare(
+    'INSERT INTO observations (id, type, data, processed, created_at) VALUES (?, ?, ?, ?, ?)'
+  );
+
+  stmt.run(id, type, JSON.stringify(data), 0, now);
+
+  return {
+    id,
+    type,
+    data,
+    processed: false,
+    created_at: now,
+  };
+}
+
+/**
+ * Get unprocessed observations
+ */
+export function getUnprocessed(limit: number = 100): Observation[] {
+  const db = getDb();
+  const stmt = db.prepare(
+    'SELECT * FROM observations WHERE processed = 0 ORDER BY created_at ASC LIMIT ?'
+  );
+  const rows = stmt.all(limit) as ObservationRow[];
+
+  return rows.map(parseObservation);
+}
+
+/**
+ * Mark an observation as processed
+ */
+export function markProcessed(id: string): void {
+  const db = getDb();
+  const stmt = db.prepare('UPDATE observations SET processed = 1 WHERE id = ?');
+  stmt.run(id);
+}
+
+/**
+ * Get recent observations, optionally filtered by type
+ */
+export function getRecentObservations(
+  type?: ObservationType,
+  limit: number = 50
+): Observation[] {
+  const db = getDb();
+
+  let query = 'SELECT * FROM observations';
+  const params: unknown[] = [];
+
+  if (type) {
+    query += ' WHERE type = ?';
+    params.push(type);
+  }
+
+  query += ' ORDER BY created_at DESC LIMIT ?';
+  params.push(limit);
+
+  const stmt = db.prepare(query);
+  const rows = stmt.all(...params as any[]) as ObservationRow[];
+
+  return rows.map(parseObservation);
+}

package/src/vault/relationships.ts

@@ -0,0 +1,178 @@
+import { getDb, generateId } from './schema.ts';
+import type { Entity } from './entities.ts';
+
+export type Relationship = {
+  id: string;
+  from_id: string;
+  to_id: string;
+  type: string;
+  properties: Record<string, unknown> | null;
+  created_at: number;
+};
+
+type RelationshipRow = {
+  id: string;
+  from_id: string;
+  to_id: string;
+  type: string;
+  properties: string | null;
+  created_at: number;
+};
+
+/**
+ * Parse relationship row from database, deserializing JSON fields
+ */
+function parseRelationship(row: RelationshipRow): Relationship {
+  return {
+    ...row,
+    properties: row.properties ? JSON.parse(row.properties) : null,
+  };
+}
+
+/**
+ * Create a new relationship between entities
+ */
+export function createRelationship(
+  from_id: string,
+  to_id: string,
+  type: string,
+  properties?: Record<string, unknown>
+): Relationship {
+  const db = getDb();
+  const id = generateId();
+  const now = Date.now();
+
+  const stmt = db.prepare(
+    'INSERT INTO relationships (id, from_id, to_id, type, properties, created_at) VALUES (?, ?, ?, ?, ?, ?)'
+  );
+
+  stmt.run(id, from_id, to_id, type, properties ? JSON.stringify(properties) : null, now);
+
+  return {
+    id,
+    from_id,
+    to_id,
+    type,
+    properties: properties ?? null,
+    created_at: now,
+  };
+}
+
+/**
+ * Get a relationship by ID
+ */
+export function getRelationship(id: string): Relationship | null {
+  const db = getDb();
+  const stmt = db.prepare('SELECT * FROM relationships WHERE id = ?');
+  const row = stmt.get(id) as RelationshipRow | null;
+
+  if (!row) return null;
+
+  return parseRelationship(row);
+}
+
+/**
+ * Find relationships matching query criteria
+ */
+export function findRelationships(query: {
+  from_id?: string;
+  to_id?: string;
+  type?: string;
+}): Relationship[] {
+  const db = getDb();
+  const conditions: string[] = [];
+  const params: unknown[] = [];
+
+  if (query.from_id) {
+    conditions.push('from_id = ?');
+    params.push(query.from_id);
+  }
+
+  if (query.to_id) {
+    conditions.push('to_id = ?');
+    params.push(query.to_id);
+  }
+
+  if (query.type) {
+    conditions.push('type = ?');
+    params.push(query.type);
+  }
+
+  const where = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+  const stmt = db.prepare(`SELECT * FROM relationships ${where} ORDER BY created_at DESC`);
+  const rows = stmt.all(...params as any[]) as RelationshipRow[];
+
+  return rows.map(parseRelationship);
+}
+
+/**
+ * Get all relationships for an entity (both incoming and outgoing) with full entity details
+ */
+export function getEntityRelationships(
+  entityId: string
+): Array<Relationship & { from_entity: Entity; to_entity: Entity }> {
+  const db = getDb();
+
+  const stmt = db.prepare(`
+    SELECT
+      r.*,
+      e1.id as from_entity_id,
+      e1.type as from_entity_type,
+      e1.name as from_entity_name,
+      e1.properties as from_entity_properties,
+      e1.created_at as from_entity_created_at,
+      e1.updated_at as from_entity_updated_at,
+      e1.source as from_entity_source,
+      e2.id as to_entity_id,
+      e2.type as to_entity_type,
+      e2.name as to_entity_name,
+      e2.properties as to_entity_properties,
+      e2.created_at as to_entity_created_at,
+      e2.updated_at as to_entity_updated_at,
+      e2.source as to_entity_source
+    FROM relationships r
+    JOIN entities e1 ON r.from_id = e1.id
+    JOIN entities e2 ON r.to_id = e2.id
+    WHERE r.from_id = ? OR r.to_id = ?
+    ORDER BY r.created_at DESC
+  `);
+
+  const rows = stmt.all(entityId, entityId) as any[];
+
+  return rows.map((row) => ({
+    id: row.id,
+    from_id: row.from_id,
+    to_id: row.to_id,
+    type: row.type,
+    properties: row.properties ? JSON.parse(row.properties) : null,
+    created_at: row.created_at,
+    from_entity: {
+      id: row.from_entity_id,
+      type: row.from_entity_type,
+      name: row.from_entity_name,
+      properties: row.from_entity_properties ? JSON.parse(row.from_entity_properties) : null,
+      created_at: row.from_entity_created_at,
+      updated_at: row.from_entity_updated_at,
+      source: row.from_entity_source,
+    },
+    to_entity: {
+      id: row.to_entity_id,
+      type: row.to_entity_type,
+      name: row.to_entity_name,
+      properties: row.to_entity_properties ? JSON.parse(row.to_entity_properties) : null,
+      created_at: row.to_entity_created_at,
+      updated_at: row.to_entity_updated_at,
+      source: row.to_entity_source,
+    },
+  }));
+}
+
+/**
+ * Delete a relationship
+ */
+export function deleteRelationship(id: string): boolean {
+  const db = getDb();
+  const stmt = db.prepare('DELETE FROM relationships WHERE id = ?');
+  const result = stmt.run(id);
+  return result.changes > 0;
+}

package/src/vault/retrieval.test.ts

@@ -0,0 +1,126 @@
+import { test, expect, beforeEach } from 'bun:test';
+import { initDatabase } from './schema.ts';
+import { createEntity } from './entities.ts';
+import { createFact } from './facts.ts';
+import { createRelationship } from './relationships.ts';
+import {
+  extractSearchTerms,
+  retrieveForMessage,
+  formatKnowledgeContext,
+  getKnowledgeForMessage,
+} from './retrieval.ts';
+
+beforeEach(() => {
+  initDatabase(':memory:');
+});
+
+// --- extractSearchTerms ---
+
+test('extractSearchTerms filters stopwords', () => {
+  const terms = extractSearchTerms('Where does John work at Google?');
+  expect(terms).toContain('john');
+  expect(terms).toContain('google');
+  expect(terms).not.toContain('where');
+  expect(terms).not.toContain('does');
+  expect(terms).not.toContain('at');
+});
+
+test('extractSearchTerms deduplicates', () => {
+  const terms = extractSearchTerms('John and John went to Google Google');
+  const johnCount = terms.filter(t => t === 'john').length;
+  expect(johnCount).toBe(1);
+});
+
+test('extractSearchTerms handles empty input', () => {
+  expect(extractSearchTerms('')).toEqual([]);
+  expect(extractSearchTerms('the is a')).toEqual([]);
+});
+
+// --- retrieveForMessage ---
+
+test('retrieveForMessage finds entities by name', () => {
+  createEntity('person', 'John', { role: 'engineer' });
+  createEntity('person', 'Anna');
+
+  const profiles = retrieveForMessage('Tell me about John');
+  expect(profiles.length).toBe(1);
+  expect(profiles[0]!.entity.name).toBe('John');
+});
+
+test('retrieveForMessage finds entities via fact objects', () => {
+  const john = createEntity('person', 'John');
+  createFact(john.id, 'works_at', 'Google');
+
+  // Search for "Google" — should find John because he has a fact with object "Google"
+  const profiles = retrieveForMessage('What do you know about Google?');
+  expect(profiles.length).toBeGreaterThanOrEqual(1);
+  const names = profiles.map(p => p.entity.name);
+  expect(names).toContain('John');
+});
+
+test('retrieveForMessage includes facts for matched entities', () => {
+  const john = createEntity('person', 'John');
+  createFact(john.id, 'works_at', 'Google');
+  createFact(john.id, 'birthday', 'March 15');
+
+  const profiles = retrieveForMessage('Tell me about John');
+  expect(profiles.length).toBe(1);
+  expect(profiles[0]!.facts.length).toBe(2);
+});
+
+test('retrieveForMessage includes relationships', () => {
+  const john = createEntity('person', 'John');
+  const google = createEntity('concept', 'Google');
+  createRelationship(john.id, google.id, 'works_at');
+
+  const profiles = retrieveForMessage('What about John?');
+  expect(profiles.length).toBeGreaterThanOrEqual(1);
+
+  const johnProfile = profiles.find(p => p.entity.name === 'John');
+  expect(johnProfile).toBeDefined();
+  expect(johnProfile!.relationships.length).toBeGreaterThanOrEqual(1);
+});
+
+test('retrieveForMessage returns empty for irrelevant query', () => {
+  createEntity('person', 'John');
+  const profiles = retrieveForMessage('the is a');
+  expect(profiles.length).toBe(0);
+});
+
+// --- formatKnowledgeContext ---
+
+test('formatKnowledgeContext formats entity with facts', () => {
+  const john = createEntity('person', 'John');
+  createFact(john.id, 'works_at', 'Google');
+
+  const profiles = retrieveForMessage('John');
+  const context = formatKnowledgeContext(profiles);
+
+  expect(context).toContain('**John** (person)');
+  expect(context).toContain('works_at: Google');
+});
+
+test('formatKnowledgeContext returns empty for no profiles', () => {
+  expect(formatKnowledgeContext([])).toBe('');
+});
+
+// --- getKnowledgeForMessage (integration) ---
+
+test('getKnowledgeForMessage end-to-end', () => {
+  const john = createEntity('person', 'John');
+  createFact(john.id, 'works_at', 'Google');
+  createFact(john.id, 'location', 'San Francisco');
+
+  const anna = createEntity('person', 'Anna');
+  createFact(anna.id, 'sister_of', 'John');
+
+  const context = getKnowledgeForMessage('Where does John live?');
+  expect(context).toContain('John');
+  expect(context).toContain('works_at: Google');
+  expect(context).toContain('location: San Francisco');
+});
+
+test('getKnowledgeForMessage handles no matches gracefully', () => {
+  const context = getKnowledgeForMessage('Tell me about quantum physics');
+  expect(context).toBe('');
+});