librefang-registry/plugins/episodic-memory/hooks/ingest.py

#!/usr/bin/env python3
"""Episodic memory ingest hook.

Loads the episode store for the current agent, scores completed episodes
against the incoming message's keywords using keyword overlap ratio, and
returns the top 2 matching episodes as contextual memories.

This hook is read-only -- it never modifies the episode store.

Receives via stdin:
    {"type": "ingest", "agent_id": "...", "message": "user message text"}

Prints to stdout:
    {"type": "ingest_result", "memories": [{"content": "..."}]}
"""
import json
import os
import re
import sys

# ---------------------------------------------------------------------------
# Stopwords & keyword extraction
# ---------------------------------------------------------------------------

STOPWORDS = frozenset({
    "a", "an", "the", "and", "or", "but", "in", "on", "at", "to", "for",
    "of", "with", "by", "from", "is", "are", "was", "were", "be", "been",
    "being", "have", "has", "had", "do", "does", "did", "will", "would",
    "could", "should", "may", "might", "shall", "can", "need", "must",
    "it", "its", "i", "me", "my", "you", "your", "he", "she", "we",
    "they", "them", "their", "this", "that", "these", "those", "what",
    "which", "who", "how", "when", "where", "why", "if", "then", "so",
    "not", "no", "just", "also", "very", "too", "about", "up", "out",
    "all", "some", "any", "each", "every", "into", "over", "after",
})

MIN_WORD_LEN = 3

# Minimum overlap ratio to consider an episode relevant
MIN_OVERLAP = 0.2

# Maximum episodes to return
MAX_RESULTS = 2


def extract_keywords(text):
    """Extract deduplicated keywords from text.

    Lowercases, removes stopwords, filters words shorter than MIN_WORD_LEN.
    """
    words = re.findall(r"[a-zA-Z][a-zA-Z0-9\-]*[a-zA-Z0-9]|[a-zA-Z]", text)
    seen = set()
    keywords = []
    for w in words:
        lower = w.lower()
        if lower not in STOPWORDS and len(lower) >= MIN_WORD_LEN and lower not in seen:
            seen.add(lower)
            keywords.append(lower)
    return keywords


def load_episode_store(agent_id):
    """Load the episode store JSON for the given agent. Returns None on failure."""
    store_dir = os.path.join(
        os.path.expanduser("~"), ".librefang", "plugins", "episodic-memory"
    )
    store_path = os.path.join(store_dir, f"{agent_id}.json")
    if not os.path.isfile(store_path):
        return None
    try:
        with open(store_path, "r", encoding="utf-8") as f:
            return json.load(f)
    except (json.JSONDecodeError, OSError):
        return None


def score_episode(episode_keywords, query_keywords):
    """Compute keyword overlap ratio between an episode and the query.

    overlap_ratio = |intersection| / |union|  (Jaccard similarity)
    """
    if not episode_keywords or not query_keywords:
        return 0.0
    ep_set = set(episode_keywords)
    q_set = set(query_keywords)
    intersection = ep_set & q_set
    union = ep_set | q_set
    if not union:
        return 0.0
    return len(intersection) / len(union)


def main():
    try:
        request = json.loads(sys.stdin.read())
    except (json.JSONDecodeError, ValueError):
        print(json.dumps({"type": "ingest_result", "memories": []}))
        return

    message = request.get("message", "")
    agent_id = request.get("agent_id", "")

    if not message.strip() or not agent_id:
        print(json.dumps({"type": "ingest_result", "memories": []}))
        return

    query_keywords = extract_keywords(message)
    if not query_keywords:
        print(json.dumps({"type": "ingest_result", "memories": []}))
        return

    store = load_episode_store(agent_id)
    if not store:
        print(json.dumps({"type": "ingest_result", "memories": []}))
        return

    episodes = store.get("episodes", [])

    # Score only completed episodes
    scored = []
    for ep in episodes:
        if ep.get("status") != "completed":
            continue
        overlap = score_episode(ep.get("keywords", []), query_keywords)
        if overlap > MIN_OVERLAP:
            scored.append((overlap, ep))

    # Sort by overlap descending, take top MAX_RESULTS
    scored.sort(key=lambda x: x[0], reverse=True)
    top = scored[:MAX_RESULTS]

    memories = []
    for _score, ep in top:
        timestamp = ep.get("ended", ep.get("started", "unknown"))
        summary = ep.get("summary", "no summary")
        memories.append({
            "content": f"[episodic-memory] Past episode ({timestamp}): {summary}"
        })

    print(json.dumps({"type": "ingest_result", "memories": memories}))


if __name__ == "__main__":
    main()