hippo-memory 0.2.0

package/dist/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../src/memory.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,oBAAY,KAAK;IACf,MAAM,WAAW;IACjB,QAAQ,aAAa;IACrB,QAAQ,aAAa;CACtB;AAED,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,GAAG,UAAU,CAAC;AAEhF,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,KAAK,CAAC;IACb,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,iBAAiB,EAAE,gBAAgB,CAAC;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAUD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,GAAE,IAAiB,GAAG,MAAM,CAmBpF;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,MAAM,CAmBhF;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,OAAO,GAAG,WAAW,CAO3E;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,MAAM,GAAE,MAAc,GAAG,MAAM,CAGzD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IACP,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,iBAAiB,CAAC,EAAE,gBAAgB,CAAC;IACrC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACZ,GACL,WAAW,CA+Bb"}

package/dist/memory.js

@@ -0,0 +1,118 @@
+/**
+ * Core data model for Hippo memory entries.
+ * Based on the strength formula from PLAN.md.
+ */
+export var Layer;
+(function (Layer) {
+    Layer["Buffer"] = "buffer";
+    Layer["Episodic"] = "episodic";
+    Layer["Semantic"] = "semantic";
+})(Layer || (Layer = {}));
+// Emotional multipliers from PLAN.md
+const EMOTIONAL_MULTIPLIERS = {
+    neutral: 1.0,
+    positive: 1.3,
+    negative: 1.5, // error-tagged
+    critical: 2.0,
+};
+/**
+ * Calculate current strength at a given time.
+ * strength(t) = base_strength * decay * retrieval_boost * emotional_multiplier
+ *
+ * Pinned memories always return 1.0 (no decay).
+ */
+export function calculateStrength(entry, now = new Date()) {
+    if (entry.pinned)
+        return 1.0;
+    const lastRetrieved = new Date(entry.last_retrieved);
+    const daysSince = (now.getTime() - lastRetrieved.getTime()) / (1000 * 60 * 60 * 24);
+    // Exponential decay: base * (0.5 ^ (days / half_life))
+    const decay = Math.pow(0.5, daysSince / entry.half_life_days);
+    // Retrieval boost: 1 + 0.1 * log2(retrieval_count + 1)
+    const retrievalBoost = 1 + 0.1 * Math.log2(entry.retrieval_count + 1);
+    // Emotional multiplier
+    const emotionalMultiplier = EMOTIONAL_MULTIPLIERS[entry.emotional_valence] ?? 1.0;
+    const raw = decay * retrievalBoost * emotionalMultiplier;
+    // Clamp to [0, 1]
+    return Math.min(1.0, Math.max(0.0, raw));
+}
+/**
+ * Derive half-life based on signals, as per PLAN.md table.
+ */
+export function deriveHalfLife(base, entry) {
+    let hl = base;
+    // Error-tagged: 2x half-life
+    if (entry.tags?.includes('error')) {
+        hl *= 2;
+    }
+    // High schema fit: consolidates faster (1.5x)
+    if (entry.schema_fit !== undefined && entry.schema_fit > 0.7) {
+        hl *= 1.5;
+    }
+    // Low schema fit: decay faster (0.5x)
+    if (entry.schema_fit !== undefined && entry.schema_fit < 0.3) {
+        hl *= 0.5;
+    }
+    return hl;
+}
+/**
+ * Apply outcome feedback to a memory entry.
+ * Positive: +5 days half-life. Negative: -3 days.
+ */
+export function applyOutcome(entry, good) {
+    const delta = good ? 5 : -3;
+    const newHalfLife = Math.max(1, entry.half_life_days + delta);
+    const newOutcome = good ? 1 : -1;
+    const updated = { ...entry, half_life_days: newHalfLife, outcome_score: newOutcome };
+    updated.strength = calculateStrength(updated);
+    return updated;
+}
+/**
+ * Generate a random memory ID.
+ */
+export function generateId(prefix = 'mem') {
+    const hex = Math.random().toString(16).slice(2, 8) + Math.random().toString(16).slice(2, 8);
+    return `${prefix}_${hex.slice(0, 8)}`;
+}
+/**
+ * Create a new memory entry with defaults.
+ */
+export function createMemory(content, options = {}) {
+    const now = new Date().toISOString();
+    const layer = options.layer ?? Layer.Episodic;
+    const tags = options.tags ?? [];
+    const emotional_valence = options.emotional_valence ?? inferValence(tags);
+    const schema_fit = options.schema_fit ?? 0.5;
+    const partial = { tags, schema_fit };
+    const half_life_days = deriveHalfLife(7, partial);
+    const entry = {
+        id: generateId(layer === Layer.Semantic ? 'sem' : 'mem'),
+        created: now,
+        last_retrieved: now,
+        retrieval_count: 0,
+        strength: 1.0,
+        half_life_days,
+        layer,
+        tags,
+        emotional_valence,
+        schema_fit,
+        source: options.source ?? 'cli',
+        outcome_score: null,
+        conflicts_with: [],
+        pinned: options.pinned ?? false,
+        content,
+    };
+    // Recalculate strength with the emotional multiplier applied
+    entry.strength = calculateStrength(entry);
+    return entry;
+}
+function inferValence(tags) {
+    if (tags.includes('critical'))
+        return 'critical';
+    if (tags.includes('error'))
+        return 'negative';
+    if (tags.includes('success') || tags.includes('win'))
+        return 'positive';
+    return 'neutral';
+}
+//# sourceMappingURL=memory.js.map

package/dist/memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.js","sourceRoot":"","sources":["../src/memory.ts"],"names":[],"mappings":"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"}

package/dist/search.d.ts

@@ -0,0 +1,51 @@
+/**
+ * BM25 search + optional embedding hybrid search for Hippo.
+ * Zero external dependencies when embeddings are not available.
+ */
+import { MemoryEntry } from './memory.js';
+/**
+ * Rough token estimate: characters / 4 (works well for English text).
+ */
+export declare function estimateTokens(text: string): number;
+export interface SearchResult {
+    entry: MemoryEntry;
+    score: number;
+    bm25: number;
+    tokens: number;
+}
+/**
+ * Hybrid search: BM25 + cosine similarity (when embeddings are available).
+ * score = 0.4 * bm25_norm + 0.6 * cosine_sim  (with embeddings)
+ * score = bm25_norm * strength * recency        (BM25-only fallback)
+ *
+ * embeddingWeight: weight for the cosine similarity component (0.0 to 1.0).
+ */
+export declare function hybridSearch(query: string, entries: MemoryEntry[], options?: {
+    budget?: number;
+    now?: Date;
+    hippoRoot?: string;
+    embeddingWeight?: number;
+}): Promise<SearchResult[]>;
+/**
+ * Search entries using BM25 + strength + recency composite score.
+ * When embeddings are available and hippoRoot is provided, uses hybrid scoring.
+ * Returns results sorted by score, capped at token budget.
+ *
+ * Also updates retrieval metadata on returned entries (side effect: caller
+ * must persist the updated entries).
+ */
+export declare function search(query: string, entries: MemoryEntry[], options?: {
+    budget?: number;
+    now?: Date;
+    hippoRoot?: string;
+}): SearchResult[];
+/**
+ * Update retrieval metadata on entries that were returned by a search.
+ * Returns the mutated copies (caller must persist to disk).
+ */
+export declare function markRetrieved(entries: MemoryEntry[], now?: Date): MemoryEntry[];
+/**
+ * Compute text overlap ratio between two strings (Jaccard on token sets).
+ */
+export declare function textOverlap(a: string, b: string): number;
+//# sourceMappingURL=search.d.ts.map

package/dist/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,WAAW,EAAqB,MAAM,aAAa,CAAC;AAkF7D;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAiBD,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,WAAW,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,WAAW,EAAE,EACtB,OAAO,GAAE;IACP,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,IAAI,CAAC;IACX,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;CACrB,GACL,OAAO,CAAC,YAAY,EAAE,CAAC,CAqFzB;AAED;;;;;;;GAOG;AACH,wBAAgB,MAAM,CACpB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,WAAW,EAAE,EACtB,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,IAAI,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GAChE,YAAY,EAAE,CA+ChB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,WAAW,EAAE,EAAE,GAAG,GAAE,IAAiB,GAAG,WAAW,EAAE,CAY3F;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAaxD"}

package/dist/search.js

@@ -0,0 +1,239 @@
+/**
+ * BM25 search + optional embedding hybrid search for Hippo.
+ * Zero external dependencies when embeddings are not available.
+ */
+import { calculateStrength } from './memory.js';
+import { isEmbeddingAvailable, getEmbedding, cosineSimilarity, loadEmbeddingIndex, } from './embeddings.js';
+// ---------------------------------------------------------------------------
+// Tokenizer
+// ---------------------------------------------------------------------------
+function tokenize(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^\w\s]/g, ' ')
+        .split(/\s+/)
+        .filter((t) => t.length > 1);
+}
+const BM25_K1 = 1.5;
+const BM25_B = 0.75;
+function buildCorpus(texts) {
+    const docs = texts.map(tokenize);
+    const N = docs.length;
+    const df = new Map();
+    let totalLen = 0;
+    for (const doc of docs) {
+        totalLen += doc.length;
+        const seen = new Set();
+        for (const term of doc) {
+            if (!seen.has(term)) {
+                df.set(term, (df.get(term) ?? 0) + 1);
+                seen.add(term);
+            }
+        }
+    }
+    const avgLen = N > 0 ? totalLen / N : 1;
+    return { docs, avgLen, df, N };
+}
+function bm25Score(corpus, docIdx, queryTerms) {
+    const doc = corpus.docs[docIdx];
+    const docLen = doc.length;
+    let score = 0;
+    // Term frequency map for this doc
+    const tf = new Map();
+    for (const t of doc)
+        tf.set(t, (tf.get(t) ?? 0) + 1);
+    for (const term of queryTerms) {
+        const f = tf.get(term) ?? 0;
+        if (f === 0)
+            continue;
+        const df = corpus.df.get(term) ?? 0;
+        const idf = Math.log((corpus.N - df + 0.5) / (df + 0.5) + 1);
+        const numerator = f * (BM25_K1 + 1);
+        const denominator = f + BM25_K1 * (1 - BM25_B + BM25_B * (docLen / corpus.avgLen));
+        score += idf * (numerator / denominator);
+    }
+    return score;
+}
+// ---------------------------------------------------------------------------
+// Token budget estimation
+// ---------------------------------------------------------------------------
+/**
+ * Rough token estimate: characters / 4 (works well for English text).
+ */
+export function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+// ---------------------------------------------------------------------------
+// Recency boost
+// ---------------------------------------------------------------------------
+function recencyBoost(entry, now) {
+    const created = new Date(entry.created);
+    const ageDays = (now.getTime() - created.getTime()) / (1000 * 60 * 60 * 24);
+    // Exponential decay: memories < 1 day get boost ~1.0, older get less
+    return Math.exp(-ageDays / 30);
+}
+/**
+ * Hybrid search: BM25 + cosine similarity (when embeddings are available).
+ * score = 0.4 * bm25_norm + 0.6 * cosine_sim  (with embeddings)
+ * score = bm25_norm * strength * recency        (BM25-only fallback)
+ *
+ * embeddingWeight: weight for the cosine similarity component (0.0 to 1.0).
+ */
+export async function hybridSearch(query, entries, options = {}) {
+    const now = options.now ?? new Date();
+    const budget = options.budget ?? 4000;
+    const embeddingWeight = options.embeddingWeight ?? 0.6;
+    const bm25Weight = 1 - embeddingWeight;
+    if (entries.length === 0)
+        return [];
+    const queryTerms = tokenize(query);
+    if (queryTerms.length === 0)
+        return [];
+    // Build BM25 corpus
+    const texts = entries.map((e) => `${e.content} ${e.tags.join(' ')}`);
+    const corpus = buildCorpus(texts);
+    // Score all entries with BM25
+    const bm25Scores = entries.map((_, i) => bm25Score(corpus, i, queryTerms));
+    const maxBm25 = Math.max(...bm25Scores, 1e-9);
+    // Try to get embedding scores if available
+    let useEmbeddings = false;
+    let embeddingIndex = {};
+    let queryVector = [];
+    if (isEmbeddingAvailable() && options.hippoRoot) {
+        try {
+            queryVector = await getEmbedding(query);
+            if (queryVector.length > 0) {
+                embeddingIndex = loadEmbeddingIndex(options.hippoRoot);
+                useEmbeddings = true;
+            }
+        }
+        catch {
+            // Fall through to BM25-only
+        }
+    }
+    // Score each entry
+    const scored = [];
+    for (let i = 0; i < entries.length; i++) {
+        const rawBm25 = bm25Scores[i];
+        if (!useEmbeddings && rawBm25 <= 0)
+            continue;
+        const normBm25 = rawBm25 / maxBm25;
+        const strength = calculateStrength(entries[i], now);
+        const recency = recencyBoost(entries[i], now);
+        let compositeScore;
+        if (useEmbeddings) {
+            const cached = embeddingIndex[entries[i].id];
+            const cosine = cached && queryVector.length > 0
+                ? cosineSimilarity(queryVector, cached)
+                : 0;
+            // Hybrid: weighted blend, then modulated by strength and recency
+            const hybrid = bm25Weight * normBm25 + embeddingWeight * Math.max(0, cosine);
+            compositeScore = hybrid * (0.5 + 0.5 * strength) * (0.8 + 0.2 * recency);
+        }
+        else {
+            // Pure BM25 path: identical to original behavior
+            const normQ = queryTerms.length > 0 ? rawBm25 / queryTerms.length : rawBm25;
+            compositeScore = normQ * (0.5 + 0.5 * strength) * (0.8 + 0.2 * recency);
+        }
+        if (compositeScore <= 0)
+            continue;
+        const tokens = estimateTokens(entries[i].content);
+        scored.push({ entry: entries[i], score: compositeScore, bm25: rawBm25, tokens });
+    }
+    // Sort by composite score descending
+    scored.sort((a, b) => b.score - a.score);
+    // Apply token budget
+    const results = [];
+    let usedTokens = 0;
+    for (const result of scored) {
+        if (usedTokens + result.tokens > budget)
+            continue;
+        results.push(result);
+        usedTokens += result.tokens;
+    }
+    return results;
+}
+/**
+ * Search entries using BM25 + strength + recency composite score.
+ * When embeddings are available and hippoRoot is provided, uses hybrid scoring.
+ * Returns results sorted by score, capped at token budget.
+ *
+ * Also updates retrieval metadata on returned entries (side effect: caller
+ * must persist the updated entries).
+ */
+export function search(query, entries, options = {}) {
+    // Synchronous path: BM25 only (no async hybrid)
+    const now = options.now ?? new Date();
+    const budget = options.budget ?? 4000;
+    if (entries.length === 0)
+        return [];
+    const queryTerms = tokenize(query);
+    if (queryTerms.length === 0)
+        return [];
+    // Build corpus from all entries (content + tags joined)
+    const texts = entries.map((e) => `${e.content} ${e.tags.join(' ')}`);
+    const corpus = buildCorpus(texts);
+    // Score each entry
+    const scored = [];
+    for (let i = 0; i < entries.length; i++) {
+        const bm25 = bm25Score(corpus, i, queryTerms);
+        if (bm25 <= 0)
+            continue;
+        const strength = calculateStrength(entries[i], now);
+        const recency = recencyBoost(entries[i], now);
+        // Composite: BM25 relevance * strength * recency
+        // Normalise BM25 against query term count to keep scale consistent
+        const normBm25 = queryTerms.length > 0 ? bm25 / queryTerms.length : bm25;
+        const composite = normBm25 * (0.5 + 0.5 * strength) * (0.8 + 0.2 * recency);
+        const tokens = estimateTokens(entries[i].content);
+        scored.push({ entry: entries[i], score: composite, bm25, tokens });
+    }
+    // Sort by composite score descending
+    scored.sort((a, b) => b.score - a.score);
+    // Apply token budget
+    const results = [];
+    let usedTokens = 0;
+    for (const result of scored) {
+        if (usedTokens + result.tokens > budget)
+            continue;
+        results.push(result);
+        usedTokens += result.tokens;
+    }
+    return results;
+}
+/**
+ * Update retrieval metadata on entries that were returned by a search.
+ * Returns the mutated copies (caller must persist to disk).
+ */
+export function markRetrieved(entries, now = new Date()) {
+    return entries.map((e) => {
+        const updated = {
+            ...e,
+            retrieval_count: e.retrieval_count + 1,
+            last_retrieved: now.toISOString(),
+            // Extend half-life by +2 days per retrieval (PLAN.md)
+            half_life_days: e.half_life_days + 2,
+        };
+        updated.strength = calculateStrength(updated, now);
+        return updated;
+    });
+}
+/**
+ * Compute text overlap ratio between two strings (Jaccard on token sets).
+ */
+export function textOverlap(a, b) {
+    const setA = new Set(tokenize(a));
+    const setB = new Set(tokenize(b));
+    if (setA.size === 0 && setB.size === 0)
+        return 1;
+    if (setA.size === 0 || setB.size === 0)
+        return 0;
+    let intersection = 0;
+    for (const t of setA) {
+        if (setB.has(t))
+            intersection++;
+    }
+    const union = setA.size + setB.size - intersection;
+    return intersection / union;
+}
+//# sourceMappingURL=search.js.map

package/dist/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAe,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EACL,oBAAoB,EACpB,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,iBAAiB,CAAC;AAEzB,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,SAAS,QAAQ,CAAC,IAAY;IAC5B,OAAO,IAAI;SACR,WAAW,EAAE;SACb,OAAO,CAAC,UAAU,EAAE,GAAG,CAAC;SACxB,KAAK,CAAC,KAAK,CAAC;SACZ,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACjC,CAAC;AAaD,MAAM,OAAO,GAAG,GAAG,CAAC;AACpB,MAAM,MAAM,GAAG,IAAI,CAAC;AAEpB,SAAS,WAAW,CAAC,KAAe;IAClC,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACjC,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;IACtB,MAAM,EAAE,GAAG,IAAI,GAAG,EAAkB,CAAC;IAErC,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,QAAQ,IAAI,GAAG,CAAC,MAAM,CAAC;QACvB,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;QAC/B,KAAK,MAAM,IAAI,IAAI,GAAG,EAAE,CAAC;YACvB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBACpB,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;gBACtC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACjB,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,MAAM,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACxC,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC;AACjC,CAAC;AAED,SAAS,SAAS,CAAC,MAAkB,EAAE,MAAc,EAAE,UAAoB;IACzE,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAChC,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;IAC1B,IAAI,KAAK,GAAG,CAAC,CAAC;IAEd,kCAAkC;IAClC,MAAM,EAAE,GAAG,IAAI,GAAG,EAAkB,CAAC;IACrC,KAAK,MAAM,CAAC,IAAI,GAAG;QAAE,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAErD,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;QAC9B,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5B,IAAI,CAAC,KAAK,CAAC;YAAE,SAAS;QAEtB,MAAM,EAAE,GAAG,MAAM,CAAC,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACpC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,GAAG,GAAG,CAAC,GAAG,CAAC,EAAE,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;QAC7D,MAAM,SAAS,GAAG,CAAC,GAAG,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC;QACpC,MAAM,WAAW,GAAG,CAAC,GAAG,OAAO,GAAG,CAAC,CAAC,GAAG,MAAM,GAAG,MAAM,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;QACnF,KAAK,IAAI,GAAG,GAAG,CAAC,SAAS,GAAG,WAAW,CAAC,CAAC;IAC3C,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,8EAA8E;AAC9E,0BAA0B;AAC1B,8EAA8E;AAE9E;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACpC,CAAC;AAED,8EAA8E;AAC9E,gBAAgB;AAChB,8EAA8E;AAE9E,SAAS,YAAY,CAAC,KAAkB,EAAE,GAAS;IACjD,MAAM,OAAO,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACxC,MAAM,OAAO,GAAG,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,IAAI,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC;IAC5E,qEAAqE;IACrE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,GAAG,EAAE,CAAC,CAAC;AACjC,CAAC;AAaD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,KAAa,EACb,OAAsB,EACtB,UAKI,EAAE;IAEN,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC;IACtC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC;IACtC,MAAM,eAAe,GAAG,OAAO,CAAC,eAAe,IAAI,GAAG,CAAC;IACvD,MAAM,UAAU,GAAG,CAAC,GAAG,eAAe,CAAC;IAEvC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEpC,MAAM,UAAU,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IACnC,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEvC,oBAAoB;IACpB,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACrE,MAAM,MAAM,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;IAElC,8BAA8B;IAC9B,MAAM,UAAU,GAAa,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC;IACrF,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,UAAU,EAAE,IAAI,CAAC,CAAC;IAE9C,2CAA2C;IAC3C,IAAI,aAAa,GAAG,KAAK,CAAC;IAC1B,IAAI,cAAc,GAA6B,EAAE,CAAC;IAClD,IAAI,WAAW,GAAa,EAAE,CAAC;IAE/B,IAAI,oBAAoB,EAAE,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;QAChD,IAAI,CAAC;YACH,WAAW,GAAG,MAAM,YAAY,CAAC,KAAK,CAAC,CAAC;YACxC,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC3B,cAAc,GAAG,kBAAkB,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;gBACvD,aAAa,GAAG,IAAI,CAAC;YACvB,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,4BAA4B;QAC9B,CAAC;IACH,CAAC;IAED,mBAAmB;IACnB,MAAM,MAAM,GAAmB,EAAE,CAAC;IAElC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACxC,MAAM,OAAO,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;QAE9B,IAAI,CAAC,aAAa,IAAI,OAAO,IAAI,CAAC;YAAE,SAAS;QAE7C,MAAM,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC;QACnC,MAAM,QAAQ,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QACpD,MAAM,OAAO,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QAE9C,IAAI,cAAsB,CAAC;QAE3B,IAAI,aAAa,EAAE,CAAC;YAClB,MAAM,MAAM,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YAC7C,MAAM,MAAM,GAAG,MAAM,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC;gBAC7C,CAAC,CAAC,gBAAgB,CAAC,WAAW,EAAE,MAAM,CAAC;gBACvC,CAAC,CAAC,CAAC,CAAC;YAEN,iEAAiE;YACjE,MAAM,MAAM,GAAG,UAAU,GAAG,QAAQ,GAAG,eAAe,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;YAC7E,cAAc,GAAG,MAAM,GAAG,CAAC,GAAG,GAAG,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,GAAG,GAAG,GAAG,OAAO,CAAC,CAAC;QAC3E,CAAC;aAAM,CAAC;YACN,iDAAiD;YACjD,MAAM,KAAK,GAAG,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;YAC5E,cAAc,GAAG,KAAK,GAAG,CAAC,GAAG,GAAG,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,GAAG,GAAG,GAAG,OAAO,CAAC,CAAC;QAC1E,CAAC;QAED,IAAI,cAAc,IAAI,CAAC;YAAE,SAAS;QAElC,MAAM,MAAM,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;QAClD,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;IACnF,CAAC;IAED,qCAAqC;IACrC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;IAEzC,qBAAqB;IACrB,MAAM,OAAO,GAAmB,EAAE,CAAC;IACnC,IAAI,UAAU,GAAG,CAAC,CAAC;IAEnB,KAAK,MAAM,MAAM,IAAI,MAAM,EAAE,CAAC;QAC5B,IAAI,UAAU,GAAG,MAAM,CAAC,MAAM,GAAG,MAAM;YAAE,SAAS;QAClD,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACrB,UAAU,IAAI,MAAM,CAAC,MAAM,CAAC;IAC9B,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,MAAM,CACpB,KAAa,EACb,OAAsB,EACtB,UAA+D,EAAE;IAEjE,gDAAgD;IAChD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC;IACtC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC;IAEtC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEpC,MAAM,UAAU,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IACnC,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEvC,wDAAwD;IACxD,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACrE,MAAM,MAAM,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;IAElC,mBAAmB;IACnB,MAAM,MAAM,GAAmB,EAAE,CAAC;IAClC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACxC,MAAM,IAAI,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC,EAAE,UAAU,CAAC,CAAC;QAC9C,IAAI,IAAI,IAAI,CAAC;YAAE,SAAS;QAExB,MAAM,QAAQ,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QACpD,MAAM,OAAO,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QAE9C,iDAAiD;QACjD,mEAAmE;QACnE,MAAM,QAAQ,GAAG,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;QACzE,MAAM,SAAS,GAAG,QAAQ,GAAG,CAAC,GAAG,GAAG,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,GAAG,GAAG,GAAG,OAAO,CAAC,CAAC;QAE5E,MAAM,MAAM,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;QAElD,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IACrE,CAAC;IAED,qCAAqC;IACrC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;IAEzC,qBAAqB;IACrB,MAAM,OAAO,GAAmB,EAAE,CAAC;IACnC,IAAI,UAAU,GAAG,CAAC,CAAC;IAEnB,KAAK,MAAM,MAAM,IAAI,MAAM,EAAE,CAAC;QAC5B,IAAI,UAAU,GAAG,MAAM,CAAC,MAAM,GAAG,MAAM;YAAE,SAAS;QAClD,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACrB,UAAU,IAAI,MAAM,CAAC,MAAM,CAAC;IAC9B,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,OAAsB,EAAE,MAAY,IAAI,IAAI,EAAE;IAC1E,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACvB,MAAM,OAAO,GAAgB;YAC3B,GAAG,CAAC;YACJ,eAAe,EAAE,CAAC,CAAC,eAAe,GAAG,CAAC;YACtC,cAAc,EAAE,GAAG,CAAC,WAAW,EAAE;YACjC,sDAAsD;YACtD,cAAc,EAAE,CAAC,CAAC,cAAc,GAAG,CAAC;SACrC,CAAC;QACF,OAAO,CAAC,QAAQ,GAAG,iBAAiB,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QACnD,OAAO,OAAO,CAAC;IACjB,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,CAAS,EAAE,CAAS;IAC9C,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAClC,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAClC,IAAI,IAAI,CAAC,IAAI,KAAK,CAAC,IAAI,IAAI,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IACjD,IAAI,IAAI,CAAC,IAAI,KAAK,CAAC,IAAI,IAAI,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAEjD,IAAI,YAAY,GAAG,CAAC,CAAC;IACrB,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;YAAE,YAAY,EAAE,CAAC;IAClC,CAAC;IAED,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;IACnD,OAAO,YAAY,GAAG,KAAK,CAAC;AAC9B,CAAC"}

package/dist/shared.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Cross-agent shared memory for Hippo.
+ * Global store at ~/.hippo/ is shared across all projects.
+ * Local .hippo/ stores are per-project.
+ */
+import { MemoryEntry } from './memory.js';
+import { SearchResult } from './search.js';
+/**
+ * Returns the path to the global Hippo store: ~/.hippo/
+ */
+export declare function getGlobalRoot(): string;
+/**
+ * Ensure the global store exists.
+ */
+export declare function initGlobal(): void;
+/**
+ * Copy a local memory entry to the global store.
+ * Assigns a new ID (prefixed with 'g_') to avoid collisions.
+ * Returns the new global entry.
+ */
+export declare function promoteToGlobal(localRoot: string, id: string): MemoryEntry;
+export interface SearchOptions {
+    budget?: number;
+    now?: Date;
+}
+/**
+ * Search across both local and global stores, merging results.
+ * Local results are boosted by 1.2x to prefer project-specific context.
+ * Returns results sorted by adjusted score, within combined token budget.
+ */
+export declare function searchBoth(query: string, localRoot: string, globalRoot: string, options?: SearchOptions): SearchResult[];
+/**
+ * Copy all global memories into the local store.
+ * Skips entries that already exist locally (by ID or by near-identical content).
+ * Returns the count of newly copied entries.
+ */
+export declare function syncGlobalToLocal(localRoot: string, globalRoot: string): number;
+//# sourceMappingURL=shared.d.ts.map

package/dist/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../src/shared.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,EAAE,WAAW,EAAc,MAAM,aAAa,CAAC;AAQtD,OAAO,EAAU,YAAY,EAAE,MAAM,aAAa,CAAC;AAEnD;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,IAAI,CAQjC;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,WAAW,CAgB1E;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,aAAkB,GAC1B,YAAY,EAAE,CAwChB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAgB/E"}

package/dist/shared.js

@@ -0,0 +1,111 @@
+/**
+ * Cross-agent shared memory for Hippo.
+ * Global store at ~/.hippo/ is shared across all projects.
+ * Local .hippo/ stores are per-project.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { generateId } from './memory.js';
+import { initStore, loadAllEntries, loadIndex, writeEntry, readEntry, } from './store.js';
+import { search } from './search.js';
+/**
+ * Returns the path to the global Hippo store: ~/.hippo/
+ */
+export function getGlobalRoot() {
+    return path.join(os.homedir(), '.hippo');
+}
+/**
+ * Ensure the global store exists.
+ */
+export function initGlobal() {
+    const globalRoot = getGlobalRoot();
+    if (!fs.existsSync(globalRoot)) {
+        initStore(globalRoot);
+    }
+    else {
+        // Ensure subdirectories exist in case partially initialized
+        initStore(globalRoot);
+    }
+}
+/**
+ * Copy a local memory entry to the global store.
+ * Assigns a new ID (prefixed with 'g_') to avoid collisions.
+ * Returns the new global entry.
+ */
+export function promoteToGlobal(localRoot, id) {
+    const entry = readEntry(localRoot, id);
+    if (!entry)
+        throw new Error(`Memory not found: ${id}`);
+    initGlobal();
+    const globalRoot = getGlobalRoot();
+    // Mint a new ID for the global store
+    const globalEntry = {
+        ...entry,
+        id: generateId('g'),
+        source: `promoted:${localRoot}`,
+    };
+    writeEntry(globalRoot, globalEntry);
+    return globalEntry;
+}
+/**
+ * Search across both local and global stores, merging results.
+ * Local results are boosted by 1.2x to prefer project-specific context.
+ * Returns results sorted by adjusted score, within combined token budget.
+ */
+export function searchBoth(query, localRoot, globalRoot, options = {}) {
+    const { budget = 4000, now = new Date() } = options;
+    const localEntries = fs.existsSync(localRoot) ? loadAllEntries(localRoot) : [];
+    const globalEntries = fs.existsSync(globalRoot) ? loadAllEntries(globalRoot) : [];
+    if (localEntries.length === 0 && globalEntries.length === 0)
+        return [];
+    // Search each store with full budget, then blend
+    const localResults = search(query, localEntries, { budget, now });
+    const globalResults = search(query, globalEntries, { budget, now });
+    // Tag global results
+    const tagged = [
+        ...localResults.map((r) => ({ ...r, isGlobal: false, score: r.score * 1.2 })),
+        ...globalResults.map((r) => ({ ...r, isGlobal: true })),
+    ];
+    // Remove duplicates: if same ID appears in both, keep the local (higher weight) one
+    const seen = new Set();
+    const deduped = tagged.filter((r) => {
+        if (seen.has(r.entry.id))
+            return false;
+        seen.add(r.entry.id);
+        return true;
+    });
+    // Sort by adjusted score descending
+    deduped.sort((a, b) => b.score - a.score);
+    // Apply combined token budget
+    const results = [];
+    let usedTokens = 0;
+    for (const r of deduped) {
+        if (usedTokens + r.tokens > budget)
+            continue;
+        results.push(r);
+        usedTokens += r.tokens;
+    }
+    return results;
+}
+/**
+ * Copy all global memories into the local store.
+ * Skips entries that already exist locally (by ID or by near-identical content).
+ * Returns the count of newly copied entries.
+ */
+export function syncGlobalToLocal(localRoot, globalRoot) {
+    if (!fs.existsSync(globalRoot))
+        return 0;
+    const globalEntries = loadAllEntries(globalRoot);
+    const localIndex = loadIndex(localRoot);
+    let count = 0;
+    for (const entry of globalEntries) {
+        // Skip if already present by ID
+        if (localIndex.entries[entry.id])
+            continue;
+        writeEntry(localRoot, entry);
+        count++;
+    }
+    return count;
+}
+//# sourceMappingURL=shared.js.map

package/dist/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../src/shared.ts"],"names":[],"mappings":"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"}