@postnesia/db 0.1.4 → 0.1.5

package/README.md

@@ -0,0 +1,63 @@
+# @postnesia/db
+
+SQLite database layer for the Postnesia memory system. Provides schema migrations, Gemini embeddings, vector search, access tracking, and importance dynamics.
+
+## Exports
+
+```ts
+import { getDb, queries, createMemory } from '@postnesia/db';
+import { embed } from '@postnesia/db/embeddings';
+import { logAccess } from '@postnesia/db/access';
+import { runConsolidation } from '@postnesia/db/importance';
+```
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `DATABASE_URL` | Yes | — | Absolute `file://` URL to the SQLite database |
+| `GEMINI_API_KEY` | Yes | — | Google Gemini API key for embeddings |
+| `EMBEDDING_MODEL` | No | `gemini-embedding-001` | Embedding model name |
+| `EMBEDDING_DIMENSIONS` | No | `768` | Embedding vector dimensions |
+
+`DATABASE_URL` must be an absolute path, e.g. `file:///home/user/workspace/memory.db`.
+
+## Setup
+
+### First-time (copies schema into your project and migrates)
+
+```bash
+npx postnesia-migrate-init
+```
+
+### Apply pending migrations
+
+```bash
+npx postnesia-migrate-dev
+```
+
+### Seed core memories
+
+Seeds the operational guide into the database as a core memory:
+
+```bash
+npx postnesia-seed
+```
+
+## Bins
+
+| Command | Description |
+|---|---|
+| `postnesia-migrate-init` | Copy `schema.prisma` to your project and run initial migration |
+| `postnesia-migrate-dev` | Run `prisma migrate dev` against your database |
+| `postnesia-seed` | Insert core bootstrap memories |
+
+## Schema Overview
+
+- `memory` — main memory records with `content`, `content_l1`, `type`, `importance`, `core`, timestamps
+- `tag` / `memory_tag` — many-to-many tag associations
+- `relationship` — directional links between memories
+- `vec_memories` — sqlite-vec virtual table for vector similarity search
+- `access_log` — read access history used by the importance system
+- `journal` — daily journal entries
+- `task` — task records with status and optional session grouping

package/dist/access.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Access Tracking System
+ * Logs when memories are retrieved and updates last_accessed on the memory row.
+ * Feeds into L1 decay calculations.
+ */
+export interface AccessLogEntry {
+    memory_id: number;
+    context?: string;
+    accessed_at: string;
+}
+/**
+ * Record that a memory was accessed (updates both access_log and memory.last_accessed)
+ */
+export declare function logAccess(memory_id: number, context?: string): void;
+export declare function getAccessCount(memory_id: number, daysBack?: number): number;
+export declare function getRecentlyAccessed(limit?: number): number[];
+export declare function getAccessHistory(memory_id: number): AccessLogEntry[];
+/**
+ * Calculate relevance boost based on access patterns
+ * Recent access + frequency = higher relevance
+ */
+export declare function calculateAccessBoost(memory_id: number): number;

package/dist/access.js

@@ -0,0 +1,63 @@
+/**
+ * Access Tracking System
+ * Logs when memories are retrieved and updates last_accessed on the memory row.
+ * Feeds into L1 decay calculations.
+ */
+import { getDb, recordAccess } from './index.js';
+/**
+ * Record that a memory was accessed (updates both access_log and memory.last_accessed)
+ */
+export function logAccess(memory_id, context) {
+    try {
+        const db = getDb(false);
+        recordAccess(db, memory_id, context);
+    }
+    catch (error) {
+        console.error(`[access-tracker] Warning: Could not log access for #${memory_id}:`, error?.message);
+    }
+}
+export function getAccessCount(memory_id, daysBack = 30) {
+    const db = getDb(true);
+    const result = db.prepare(`
+    SELECT COUNT(*) as count
+    FROM access_log
+    WHERE memory_id = ?
+      AND accessed_at > datetime('now', '-${daysBack} days')
+  `).get(memory_id);
+    return result.count;
+}
+export function getRecentlyAccessed(limit = 20) {
+    const db = getDb(true);
+    const results = db.prepare(`
+    SELECT memory_id, COUNT(*) as access_count
+    FROM access_log
+    WHERE accessed_at > datetime('now', '-7 days')
+    GROUP BY memory_id
+    ORDER BY access_count DESC, MAX(accessed_at) DESC
+    LIMIT ?
+  `).all(limit);
+    return results.map(r => r.memory_id);
+}
+export function getAccessHistory(memory_id) {
+    const db = getDb(true);
+    return db.prepare(`
+    SELECT memory_id, accessed_at, context
+    FROM access_log
+    WHERE memory_id = ?
+    ORDER BY accessed_at DESC
+    LIMIT 50
+  `).all(memory_id);
+}
+/**
+ * Calculate relevance boost based on access patterns
+ * Recent access + frequency = higher relevance
+ */
+export function calculateAccessBoost(memory_id) {
+    const last7Days = getAccessCount(memory_id, 7);
+    const last30Days = getAccessCount(memory_id, 30);
+    const recentWeight = last7Days * 2;
+    const olderWeight = (last30Days - last7Days);
+    const totalScore = recentWeight + olderWeight;
+    // Normalize to 0-2 range
+    return Math.min(2, totalScore / 5);
+}

package/dist/embeddings.d.ts

@@ -4,7 +4,7 @@
  * Used by sqlite-vec for semantic similarity search (L2 retrieval)
  */
 import 'dotenv/config';
-export declare const EMBEDDING_DIMENSIONS = 768;
+export declare const EMBEDDING_DIMENSIONS: number;
 /**
  * Generate an embedding vector for a text string.
  * Returns a Float32Array suitable for sqlite-vec storage.

package/dist/embeddings.js

@@ -5,8 +5,8 @@
  */
 import 'dotenv/config';
 import { GoogleGenAI } from '@google/genai';
-export const EMBEDDING_DIMENSIONS = 768;
-const EMBEDDING_MODEL = 'gemini-embedding-001';
+export const EMBEDDING_DIMENSIONS = parseInt(process.env.EMBEDDING_DIMENSIONS ?? '768', 10);
+const EMBEDDING_MODEL = process.env.EMBEDDING_MODEL ?? 'gemini-embedding-001';
 function getClient() {
     const key = process.env.GEMINI_API_KEY;
     if (!key)

package/dist/importance.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Importance Dynamics
+ * Adjust memory importance based on age, access patterns, and relationships
+ */
+export interface ImportanceFactors {
+    baseImportance: number;
+    ageDecay: number;
+    accessBoost: number;
+    relationshipBoost: number;
+    finalScore: number;
+}
+/**
+ * Calculate age decay factor
+ * Recent memories maintain importance, old ones decay unless accessed
+ */
+export declare function calculateAgeDecay(timestamp: string): number;
+/**
+ * Calculate dynamic importance score
+ * Base importance + access boost - age decay
+ */
+export declare function calculateDynamicImportance(memory_id: number): ImportanceFactors;
+/**
+ * Get memories eligible for L1 based on dynamic scoring.
+ */
+export declare function getL1Candidates(limit?: number): Array<{
+    id: number;
+    type: string;
+    content_l1: string;
+    timestamp: string;
+    last_accessed: string;
+    baseImportance: number;
+    dynamicScore: number;
+}>;
+/**
+ * Consolidation: Review and adjust importances based on access patterns
+ */
+export declare function runConsolidation(): {
+    reviewed: number;
+    boosted: number;
+    decayed: number;
+    unchanged: number;
+};

package/dist/importance.js

@@ -0,0 +1,141 @@
+/**
+ * Importance Dynamics
+ * Adjust memory importance based on age, access patterns, and relationships
+ */
+import { getDb, queries } from './index.js';
+import { calculateAccessBoost } from './access.js';
+/**
+ * Calculate relationship boost based on graph connectivity
+ * Memories that are hubs in the relationship graph are more valuable
+ */
+function calculateRelationshipBoost(memory_id) {
+    const db = getDb(true);
+    // Count total connections
+    const connections = db.prepare(`
+    SELECT COUNT(*) as count
+    FROM relationship
+    WHERE from_id = ? OR to_id = ?
+  `).get(memory_id, memory_id);
+    // Count connections to high-importance memories (4+)
+    const importantConnections = db.prepare(`
+    SELECT COUNT(*) as count
+    FROM relationship r
+    JOIN memory m ON (
+      CASE
+        WHEN r.from_id = ? THEN m.id = r.to_id
+        ELSE m.id = r.from_id
+      END
+    )
+    WHERE (r.from_id = ? OR r.to_id = ?)
+      AND m.importance >= 4
+  `).get(memory_id, memory_id, memory_id);
+    // Boost calculation:
+    // - Base: 0.1 per connection (up to +1.0 for 10 connections)
+    // - Bonus: +0.2 per important connection
+    const baseBoost = Math.min(1.0, connections.count * 0.1);
+    const importantBonus = importantConnections.count * 0.2;
+    return Math.min(2.0, baseBoost + importantBonus);
+}
+/**
+ * Calculate age decay factor
+ * Recent memories maintain importance, old ones decay unless accessed
+ */
+export function calculateAgeDecay(timestamp) {
+    const now = Date.now();
+    const memoryDate = new Date(timestamp).getTime();
+    const ageInDays = (now - memoryDate) / (1000 * 60 * 60 * 24);
+    // No decay for first 7 days
+    if (ageInDays <= 7)
+        return 0;
+    // Gradual decay: -0.1 per week after first week
+    const weeksOld = Math.floor((ageInDays - 7) / 7);
+    const decay = Math.min(2, weeksOld * 0.1); // Max -2 importance
+    return -decay;
+}
+/**
+ * Calculate dynamic importance score
+ * Base importance + access boost - age decay
+ */
+export function calculateDynamicImportance(memory_id) {
+    const db = getDb(true);
+    const memory = db.prepare(`
+    SELECT importance, timestamp
+    FROM memory
+    WHERE id = ?
+  `).get(memory_id);
+    if (!memory) {
+        return {
+            baseImportance: 0,
+            ageDecay: 0,
+            accessBoost: 0,
+            relationshipBoost: 0,
+            finalScore: 0,
+        };
+    }
+    const baseImportance = memory.importance;
+    const ageDecay = calculateAgeDecay(memory.timestamp);
+    const accessBoost = calculateAccessBoost(memory_id);
+    const relationshipBoost = calculateRelationshipBoost(memory_id);
+    // Final score: base + boosts + decay (decay is negative)
+    const finalScore = Math.max(1, Math.min(5, baseImportance + accessBoost + relationshipBoost + ageDecay));
+    return {
+        baseImportance,
+        ageDecay,
+        accessBoost,
+        relationshipBoost,
+        finalScore: Math.round(finalScore * 10) / 10,
+    };
+}
+/**
+ * Get memories eligible for L1 based on dynamic scoring.
+ */
+export function getL1Candidates(limit = 50) {
+    const db = getDb(true);
+    const memories = queries.getL1Summaries(db).all();
+    return memories.slice(0, limit).map(m => ({
+        id: m.id,
+        type: m.type,
+        content_l1: m.content_l1,
+        timestamp: m.timestamp,
+        last_accessed: m.last_accessed,
+        baseImportance: m.importance,
+        dynamicScore: m.effective_importance,
+    }));
+}
+/**
+ * Consolidation: Review and adjust importances based on access patterns
+ */
+export function runConsolidation() {
+    const db = getDb(false);
+    let reviewed = 0;
+    let boosted = 0;
+    let decayed = 0;
+    let unchanged = 0;
+    const memories = db.prepare(`
+    SELECT id, importance, timestamp
+    FROM memory
+    WHERE timestamp > datetime('now', '-60 days')
+  `).all();
+    for (const memory of memories) {
+        reviewed++;
+        const factors = calculateDynamicImportance(memory.id);
+        const newImportance = Math.round(factors.finalScore);
+        if (newImportance !== memory.importance) {
+            db.prepare(`
+        UPDATE memory
+        SET importance = ?
+        WHERE id = ?
+      `).run(newImportance, memory.id);
+            if (newImportance > memory.importance) {
+                boosted++;
+            }
+            else {
+                decayed++;
+            }
+        }
+        else {
+            unchanged++;
+        }
+    }
+    return { reviewed, boosted, decayed, unchanged };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@postnesia/db",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "AI Agent memory context database",
   "type": "module",
   "private": false,
@@ -25,6 +25,14 @@
     "./embeddings": {
       "types": "./dist/embeddings.d.ts",
       "import": "./dist/embeddings.js"
+    },
+    "./access": {
+      "types": "./dist/access.d.ts",
+      "import": "./dist/access.js"
+    },
+    "./importance": {
+      "types": "./dist/importance.d.ts",
+      "import": "./dist/importance.js"
     }
   },
   "dependencies": {