@openanonymity/nanomem 0.1.0

package/src/bullets/normalize.js

@@ -0,0 +1,241 @@
+/**
+ * Normalization utilities for memory bullet metadata.
+ * @import { Tier, Status, Source, Confidence, Bullet, EnsureBulletMetadataOptions } from '../types.js'
+ */
+
+/**
+ * @param {string | number | null | undefined} value
+ * @returns {string | null}
+ */
+export function safeDateIso(value) {
+    if (!value) return null;
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime())) return null;
+    return date.toISOString().slice(0, 10);
+}
+
+/** @returns {string} */
+export function todayIsoDate() {
+    return new Date().toISOString().slice(0, 10);
+}
+
+/**
+ * @param {string} path
+ * @returns {string}
+ */
+export function inferTopicFromPath(path) {
+    if (!path || typeof path !== 'string') return 'general';
+    const first = path.split('/')[0]?.trim().toLowerCase();
+    return first || 'general';
+}
+
+/**
+ * @param {string} value
+ * @param {string} [fallback]
+ * @returns {string}
+ */
+export function normalizeTopic(value, fallback = 'general') {
+    const source = String(value || '').trim().toLowerCase();
+    const normalized = source
+        .replace(/[^a-z0-9/_-]+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^[-/]+|[-/]+$/g, '');
+    return normalized || fallback;
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+export function normalizeFactText(value) {
+    return String(value || '')
+        .toLowerCase()
+        .replace(/[^\w\s]/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+
+/**
+ * @param {string | null | undefined} value
+ * @param {Tier} [fallback]
+ * @returns {Tier}
+ */
+export function normalizeTier(value, fallback = 'long_term') {
+    const source = String(value || '').trim().toLowerCase();
+    if (['working', 'short_term', 'short-term'].includes(source)) return 'working';
+    if (['long_term', 'long-term', 'longterm', 'active'].includes(source)) return 'long_term';
+    if (['history', 'archive', 'archived'].includes(source)) return 'history';
+    return fallback;
+}
+
+/**
+ * @param {string | null | undefined} value
+ * @param {Status} [fallback]
+ * @returns {Status}
+ */
+export function normalizeStatus(value, fallback = 'active') {
+    const source = String(value || '').trim().toLowerCase();
+    if (['active', 'current'].includes(source)) return 'active';
+    if (['superseded', 'replaced', 'resolved'].includes(source)) return 'superseded';
+    if (['expired', 'stale'].includes(source)) return 'expired';
+    if (['uncertain', 'tentative'].includes(source)) return 'uncertain';
+    return fallback;
+}
+
+/**
+ * @param {string | null | undefined} value
+ * @param {Source} [fallback]
+ * @returns {Source}
+ */
+export function normalizeSource(value, fallback = 'user_statement') {
+    const source = String(value || '').trim().toLowerCase();
+    if (['user_statement', 'user', 'explicit_user'].includes(source)) return 'user_statement';
+    if (['assistant_summary', 'assistant', 'summary'].includes(source)) return 'assistant_summary';
+    if (['inference', 'inferred'].includes(source)) return 'inference';
+    if (['system', 'system_note'].includes(source)) return 'system';
+    return fallback;
+}
+
+/**
+ * @param {string | null | undefined} value
+ * @param {Confidence} [fallback]
+ * @returns {Confidence}
+ */
+export function normalizeConfidence(value, fallback = 'medium') {
+    const source = String(value || '').trim().toLowerCase();
+    if (['high', 'strong'].includes(source)) return 'high';
+    if (['medium', 'med', 'moderate'].includes(source)) return 'medium';
+    if (['low', 'weak'].includes(source)) return 'low';
+    return fallback;
+}
+
+/**
+ * @param {Source | string | null | undefined} source
+ * @returns {Confidence}
+ */
+export function defaultConfidenceForSource(source) {
+    if (source === 'user_statement') return 'high';
+    if (source === 'assistant_summary') return 'medium';
+    if (source === 'system') return 'medium';
+    return 'low';
+}
+
+/**
+ * @param {string} section
+ * @returns {Tier}
+ */
+export function inferTierFromSection(section) {
+    if (section === 'working') return 'working';
+    if (section === 'history') return 'history';
+    return 'long_term';
+}
+
+/**
+ * @param {string} section
+ * @returns {Status}
+ */
+export function inferStatusFromSection(section) {
+    return section === 'history' ? 'superseded' : 'active';
+}
+
+/**
+ * @param {string} value
+ * @returns {Tier}
+ */
+export function normalizeTierToSection(value) {
+    const tier = normalizeTier(value);
+    if (tier === 'working') return 'working';
+    if (tier === 'history') return 'history';
+    return 'long_term';
+}
+
+/**
+ * @param {Partial<Bullet>} bullet
+ * @param {Tier} [fallback]
+ * @returns {Tier}
+ */
+export function inferTierFromBullet(bullet, fallback = 'long_term') {
+    if (bullet?.reviewAt || bullet?.expiresAt) return 'working';
+
+    const text = String(bullet?.text || '').toLowerCase();
+    if (!text) return fallback;
+
+    const workingPatterns = [
+        /\bcurrently\b/,
+        /\bright now\b/,
+        /\bthis (week|month|quarter|year)\b/,
+        /\bnext (week|month|quarter|year)\b/,
+        /\bplanning\b/,
+        /\bevaluating\b/,
+        /\bconsidering\b/,
+        /\btrying to\b/,
+        /\bworking on\b/,
+        /\bdebugging\b/,
+        /\bpreparing\b/,
+        /\binterviewing\b/,
+        /\bin progress\b/,
+        /\btemporary\b/,
+        /\bfor now\b/,
+        /\bas of \d{4}-\d{2}-\d{2}\b/
+    ];
+
+    return workingPatterns.some((pattern) => pattern.test(text)) ? 'working' : fallback;
+}
+
+/**
+ * @param {Partial<Bullet>} bullet
+ * @param {EnsureBulletMetadataOptions} [options]
+ * @returns {Bullet}
+ */
+export function ensureBulletMetadata(bullet, options = {}) {
+    const fallbackTopic = normalizeTopic(options.defaultTopic || 'general');
+    const fallbackUpdatedAt = options.updatedAt || todayIsoDate();
+    const inferredTier = inferTierFromBullet(bullet, options.defaultTier || 'long_term');
+    const preferredTier = bullet?.explicitTier ? bullet?.tier : inferredTier;
+    const fallbackTier = normalizeTier(options.defaultTier || preferredTier || bullet?.tier || 'long_term');
+    const fallbackStatus = normalizeStatus(
+        options.defaultStatus
+            || (bullet?.explicitStatus ? bullet?.status : null)
+            || inferStatusFromSection(normalizeTierToSection(fallbackTier))
+    );
+    return {
+        text: String(bullet?.text || '').trim(),
+        topic: normalizeTopic(bullet?.topic || fallbackTopic, fallbackTopic),
+        updatedAt: safeDateIso(bullet?.updatedAt) || fallbackUpdatedAt,
+        expiresAt: safeDateIso(bullet?.expiresAt),
+        reviewAt: safeDateIso(bullet?.reviewAt),
+        tier: normalizeTier(preferredTier, fallbackTier),
+        status: normalizeStatus(bullet?.status, fallbackStatus),
+        source: normalizeSource(
+            bullet?.source,
+            normalizeSource(options.defaultSource, 'user_statement')
+        ),
+        confidence: normalizeConfidence(
+            bullet?.confidence,
+            normalizeConfidence(
+                options.defaultConfidence,
+                defaultConfidenceForSource(normalizeSource(
+                    bullet?.source,
+                    normalizeSource(options.defaultSource, 'user_statement')
+                ))
+            )
+        ),
+        explicitTier: Boolean(bullet?.explicitTier || bullet?.tier),
+        explicitStatus: Boolean(bullet?.explicitStatus || bullet?.status),
+        explicitSource: Boolean(bullet?.explicitSource || bullet?.source),
+        explicitConfidence: Boolean(bullet?.explicitConfidence || bullet?.confidence),
+        heading: String(bullet?.heading || 'General'),
+        section: normalizeTierToSection(preferredTier || fallbackTier),
+        lineIndex: Number.isFinite(bullet?.lineIndex) ? /** @type {number} */ (bullet.lineIndex) : 0
+    };
+}
+
+/**
+ * @param {Bullet} bullet
+ * @param {string} [today]
+ * @returns {boolean}
+ */
+export function isExpiredBullet(bullet, today = todayIsoDate()) {
+    if (!bullet?.expiresAt) return false;
+    return String(bullet.expiresAt) < String(today);
+}

package/src/bullets/parser.js

@@ -0,0 +1,199 @@
+/**
+ * Parsing and rendering for memory bullets.
+ */
+/** @import { Bullet } from '../types.js' */
+import {
+    safeDateIso,
+    normalizeTier,
+    normalizeStatus,
+    normalizeSource,
+    normalizeConfidence,
+    normalizeTopic,
+    normalizeTierToSection,
+    inferTierFromSection,
+    inferStatusFromSection,
+    ensureBulletMetadata,
+} from './normalize.js';
+
+const BULLET_REGEX = /^\s*-\s+(.*)$/;
+const HEADING_REGEX = /^\s{0,3}#{1,6}\s+(.*)$/;
+
+/**
+ * @param {string} content
+ * @returns {Bullet[]}
+ */
+export function parseBullets(content) {
+    const lines = String(content || '').split('\n');
+    const bullets = [];
+    let currentHeading = 'General';
+    let section = 'long_term';
+
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const headingMatch = line.match(HEADING_REGEX);
+        if (headingMatch) {
+            currentHeading = headingMatch[1].trim() || currentHeading;
+            if (/^(working)$/i.test(currentHeading)) {
+                section = 'working';
+            } else if (/^(long[- ]?term|active)$/i.test(currentHeading)) {
+                section = 'long_term';
+            } else if (/^(history|archive)$/i.test(currentHeading)) {
+                section = 'history';
+            }
+            continue;
+        }
+
+        const bulletMatch = line.match(BULLET_REGEX);
+        if (!bulletMatch) continue;
+
+        const raw = bulletMatch[1].trim();
+        const parts = raw.split('|').map((part) => part.trim()).filter(Boolean);
+        if (parts.length === 0) continue;
+
+        const text = parts.shift() || '';
+        let topic = null;
+        let updatedAt = null;
+        let expiresAt = null;
+        let reviewAt = null;
+        let tier = null;
+        let status = null;
+        let source = null;
+        let confidence = null;
+
+        for (const part of parts) {
+            const kv = part.match(/^([a-z_]+)\s*=\s*(.+)$/i);
+            if (!kv) continue;
+            const key = kv[1].toLowerCase();
+            const value = kv[2].trim();
+            if (key === 'topic') topic = value;
+            if (key === 'updated_at') updatedAt = safeDateIso(value);
+            if (key === 'expires_at') expiresAt = safeDateIso(value);
+            if (key === 'review_at') reviewAt = safeDateIso(value);
+            if (key === 'tier') tier = normalizeTier(value);
+            if (key === 'status') status = normalizeStatus(value);
+            if (key === 'source') source = normalizeSource(value);
+            if (key === 'confidence') confidence = normalizeConfidence(value);
+        }
+
+        bullets.push({
+            text,
+            topic: topic ? normalizeTopic(topic) : null,
+            updatedAt,
+            expiresAt,
+            reviewAt,
+            tier: tier || inferTierFromSection(section),
+            status: status || inferStatusFromSection(section),
+            source: source || null,
+            confidence: confidence || null,
+            explicitTier: Boolean(tier),
+            explicitStatus: Boolean(status),
+            explicitSource: Boolean(source),
+            explicitConfidence: Boolean(confidence),
+            heading: currentHeading,
+            section,
+            lineIndex: i
+        });
+    }
+
+    return bullets;
+}
+
+/**
+ * @param {string} content
+ * @returns {number}
+ */
+export function countBullets(content) {
+    return parseBullets(content).length;
+}
+
+/**
+ * @param {string} content
+ * @returns {string[]}
+ */
+export function extractTitles(content) {
+    const lines = String(content || '').split('\n');
+    const titles = [];
+
+    for (const line of lines) {
+        const headingMatch = line.match(HEADING_REGEX);
+        if (!headingMatch) continue;
+
+        const title = headingMatch[1].trim();
+        if (!title) continue;
+        if (/^(working|long[- ]?term|history|active|archive|current context|stable facts|no longer current)$/i.test(title)) continue;
+        titles.push(title);
+    }
+
+    return titles;
+}
+
+/**
+ * @param {Partial<Bullet>} bullet
+ * @returns {string}
+ */
+export function renderBullet(bullet) {
+    const clean = ensureBulletMetadata(bullet);
+    const metadata = [
+        `topic=${clean.topic}`,
+        `tier=${clean.tier}`,
+        `status=${clean.status}`,
+        `source=${clean.source}`,
+        `confidence=${clean.confidence}`,
+        `updated_at=${clean.updatedAt}`
+    ];
+    if (clean.reviewAt) metadata.push(`review_at=${clean.reviewAt}`);
+    if (clean.expiresAt) metadata.push(`expires_at=${clean.expiresAt}`);
+    return `- ${clean.text} | ${metadata.join(' | ')}`;
+}
+
+function topicHeading(topic) {
+    const clean = String(topic || 'general').trim();
+    if (!clean) return 'General';
+    return clean
+        .split(/[\/_-]+/)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join(' ');
+}
+
+function inferDocumentTopic(bullets, fallback = 'general') {
+    const firstTopic = (bullets || []).find((bullet) => bullet?.topic)?.topic;
+    return firstTopic || fallback;
+}
+
+function renderSection(lines, title, subsectionTitle, bullets, forceHistory = false) {
+    lines.push(`## ${title}`);
+    lines.push(`### ${subsectionTitle}`);
+
+    if (!bullets || bullets.length === 0) {
+        lines.push('_No entries yet._');
+        return;
+    }
+
+    for (const bullet of bullets) {
+        const nextBullet = forceHistory
+            ? { ...bullet, tier: 'history', status: bullet.status === 'active' ? 'superseded' : bullet.status, section: 'history' }
+            : bullet;
+        lines.push(renderBullet(nextBullet));
+    }
+}
+
+/**
+ * @param {Bullet[]} working
+ * @param {Bullet[]} longTerm
+ * @param {Bullet[]} history
+ * @param {{ titleTopic?: string }} [options]
+ * @returns {string}
+ */
+export function renderCompactedDocument(working, longTerm, history, options = {}) {
+    const lines = [];
+    const docTopic = normalizeTopic(options.titleTopic || inferDocumentTopic([...working, ...longTerm, ...history], 'general'));
+    lines.push(`# Memory: ${topicHeading(docTopic)}`);
+    lines.push('');
+    renderSection(lines, 'Working', 'Current context', working);
+    lines.push('');
+    renderSection(lines, 'Long-Term', 'Stable facts', longTerm);
+    lines.push('');
+    renderSection(lines, 'History', 'No longer current', history, true);
+
+    return lines.join('\n').trim();
+}

package/src/bullets/scoring.js

@@ -0,0 +1,53 @@
+/**
+ * Relevance scoring for memory bullet retrieval.
+ */
+/** @import { Bullet } from '../types.js' */
+import {
+    normalizeTier,
+    normalizeStatus,
+    normalizeSource,
+    normalizeTierToSection,
+    inferStatusFromSection,
+} from './normalize.js';
+
+/**
+ * @param {Partial<Bullet>} bullet
+ * @param {string[]} [queryTerms]
+ * @returns {number}
+ */
+export function scoreBullet(bullet, queryTerms = []) {
+    const text = String(bullet?.text || '').toLowerCase();
+    const topic = String(bullet?.topic || '').toLowerCase();
+    const tier = normalizeTier(bullet?.tier || bullet?.section || 'long_term');
+    const status = normalizeStatus(bullet?.status || inferStatusFromSection(normalizeTierToSection(tier)));
+    if (!text) return 0;
+
+    let score = 0;
+    for (const term of queryTerms) {
+        if (!term) continue;
+        if (text.includes(term)) score += 2;
+        if (topic.includes(term)) score += 1;
+    }
+    if (tier === 'working') score += 2;
+    if (tier === 'long_term') score += 1;
+    if (status === 'active') score += 2;
+    if (status === 'uncertain') score -= 1;
+    if (status === 'expired' || status === 'superseded' || tier === 'history') score -= 3;
+    if (bullet?.source === 'user_statement') score += 2;
+    if (bullet?.source === 'inference') score -= 1;
+    if (bullet?.confidence === 'high') score += 1;
+    if (bullet?.confidence === 'low') score -= 1;
+    return score;
+}
+
+/**
+ * @param {string} query
+ * @returns {string[]}
+ */
+export function tokenizeQuery(query) {
+    return String(query || '')
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .map((t) => t.trim())
+        .filter((t) => t.length >= 3);
+}