nexo-brain 3.2.0 → 4.0.0

package/src/media_memory.py

@@ -0,0 +1,303 @@
+from __future__ import annotations
+
+"""Lightweight multimodal memory reference layer."""
+
+import json
+import mimetypes
+import os
+from pathlib import Path
+
+from db import get_db
+from memory_backends import get_backend
+
+
+def _safe_json_loads(raw: str | dict | None) -> dict:
+    if isinstance(raw, dict):
+        return raw
+    if not raw:
+        return {}
+    try:
+        value = json.loads(str(raw))
+        return value if isinstance(value, dict) else {}
+    except Exception:
+        return {}
+
+
+def _serialize_metadata(metadata: dict | None) -> str:
+    if not metadata:
+        return "{}"
+    return json.dumps(metadata, ensure_ascii=True, sort_keys=True)
+
+
+def _serialize_tags(tags: str | list[str] | tuple[str, ...] | None) -> str:
+    if isinstance(tags, str):
+        items = [part.strip() for part in tags.replace("\n", ",").split(",")]
+    else:
+        items = [str(item).strip() for item in (tags or [])]
+    clean = sorted({item for item in items if item})
+    return ",".join(clean)
+
+
+def _normalized_path(file_path: str = "") -> str:
+    raw = (file_path or "").strip()
+    if not raw:
+        return ""
+    return str(Path(raw).expanduser().resolve())
+
+
+def _detect_media_type(file_path: str = "", url: str = "", mime_type: str = "") -> str:
+    mime_guess = mime_type or mimetypes.guess_type(file_path or url or "")[0] or ""
+    lowered = mime_guess.lower()
+    if lowered.startswith("image/"):
+        return "image"
+    if lowered.startswith("audio/"):
+        return "audio"
+    if lowered.startswith("video/"):
+        return "video"
+    suffix = (Path(file_path or url).suffix or "").lower()
+    if suffix in {".png", ".jpg", ".jpeg", ".gif", ".webp", ".svg"}:
+        return "image"
+    if suffix in {".mp3", ".wav", ".m4a", ".aac", ".ogg"}:
+        return "audio"
+    if suffix in {".mp4", ".mov", ".avi", ".mkv", ".webm"}:
+        return "video"
+    if suffix in {".pdf"}:
+        return "document"
+    return "file"
+
+
+def init_tables() -> None:
+    conn = get_db()
+    conn.executescript(
+        """
+        CREATE TABLE IF NOT EXISTS media_memories (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            file_path TEXT DEFAULT '',
+            url TEXT DEFAULT '',
+            media_type TEXT NOT NULL DEFAULT 'file',
+            mime_type TEXT DEFAULT '',
+            title TEXT NOT NULL DEFAULT '',
+            description TEXT DEFAULT '',
+            tags TEXT DEFAULT '',
+            domain TEXT DEFAULT '',
+            source_type TEXT DEFAULT '',
+            source_id TEXT DEFAULT '',
+            backend_key TEXT DEFAULT 'sqlite',
+            metadata TEXT DEFAULT '{}',
+            created_at TEXT DEFAULT (datetime('now')),
+            updated_at TEXT DEFAULT (datetime('now'))
+        );
+        CREATE INDEX IF NOT EXISTS idx_media_memories_type ON media_memories(media_type);
+        CREATE INDEX IF NOT EXISTS idx_media_memories_domain ON media_memories(domain);
+        CREATE INDEX IF NOT EXISTS idx_media_memories_source ON media_memories(source_type, source_id);
+        CREATE INDEX IF NOT EXISTS idx_media_memories_path ON media_memories(file_path);
+        CREATE INDEX IF NOT EXISTS idx_media_memories_url ON media_memories(url);
+        """
+    )
+    conn.commit()
+
+
+def _safe_cognitive_ingest(text: str, source_id: str, title: str, domain: str) -> None:
+    try:
+        import cognitive
+
+        cognitive.ingest(text, "media_memory", source_id, title[:120], domain)
+    except Exception:
+        pass
+
+
+def _row_to_dict(row) -> dict:
+    result = dict(row)
+    result["metadata"] = _safe_json_loads(result.get("metadata"))
+    result["tags_list"] = [item for item in str(result.get("tags", "")).split(",") if item]
+    return result
+
+
+def add_media_memory(
+    *,
+    file_path: str = "",
+    url: str = "",
+    title: str = "",
+    description: str = "",
+    tags: str | list[str] | tuple[str, ...] | None = None,
+    domain: str = "",
+    source_type: str = "",
+    source_id: str = "",
+    metadata: str | dict | None = None,
+) -> dict:
+    init_tables()
+    normalized_path = _normalized_path(file_path)
+    clean_url = (url or "").strip()
+    if not normalized_path and not clean_url:
+        return {"error": "file_path or url is required"}
+
+    conn = get_db()
+    existing = None
+    if normalized_path:
+        existing = conn.execute(
+            "SELECT * FROM media_memories WHERE file_path = ? LIMIT 1",
+            (normalized_path,),
+        ).fetchone()
+    elif clean_url:
+        existing = conn.execute(
+            "SELECT * FROM media_memories WHERE url = ? LIMIT 1",
+            (clean_url,),
+        ).fetchone()
+
+    metadata_dict = _safe_json_loads(metadata)
+    if normalized_path and os.path.exists(normalized_path):
+        stat = os.stat(normalized_path)
+        metadata_dict.setdefault("size_bytes", int(stat.st_size))
+        metadata_dict.setdefault("mtime_epoch", float(stat.st_mtime))
+
+    resolved_title = (title or Path(normalized_path or clean_url).name or "media-memory").strip()
+    resolved_tags = _serialize_tags(tags)
+    media_type = _detect_media_type(normalized_path, clean_url, metadata_dict.get("mime_type", ""))
+    mime_type = str(metadata_dict.get("mime_type", mimetypes.guess_type(normalized_path or clean_url)[0] or ""))
+
+    if existing:
+        merged_description = description.strip() or existing["description"] or ""
+        merged_tags = _serialize_tags(",".join(filter(None, [existing["tags"], resolved_tags])))
+        merged_metadata = _safe_json_loads(existing["metadata"])
+        merged_metadata.update(metadata_dict)
+        conn.execute(
+            """
+            UPDATE media_memories
+               SET title = ?,
+                   description = ?,
+                   tags = ?,
+                   domain = ?,
+                   source_type = ?,
+                   source_id = ?,
+                   media_type = ?,
+                   mime_type = ?,
+                   metadata = ?,
+                   updated_at = datetime('now')
+             WHERE id = ?
+            """,
+            (
+                resolved_title or existing["title"],
+                merged_description,
+                merged_tags,
+                domain.strip() or existing["domain"],
+                source_type.strip() or existing["source_type"],
+                source_id.strip() or existing["source_id"],
+                media_type or existing["media_type"],
+                mime_type or existing["mime_type"],
+                _serialize_metadata(merged_metadata),
+                existing["id"],
+            ),
+        )
+        conn.commit()
+        row = conn.execute("SELECT * FROM media_memories WHERE id = ?", (existing["id"],)).fetchone()
+        return _row_to_dict(row)
+
+    backend = get_backend()
+    cursor = conn.execute(
+        """
+        INSERT INTO media_memories (
+            file_path, url, media_type, mime_type, title, description, tags,
+            domain, source_type, source_id, backend_key, metadata
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        """,
+        (
+            normalized_path,
+            clean_url,
+            media_type,
+            mime_type,
+            resolved_title,
+            description.strip(),
+            resolved_tags,
+            domain.strip(),
+            source_type.strip(),
+            source_id.strip(),
+            backend.key,
+            _serialize_metadata(metadata_dict),
+        ),
+    )
+    conn.commit()
+    media_id = int(cursor.lastrowid)
+    _safe_cognitive_ingest(
+        (
+            f"Media memory [{media_type}] {resolved_title}. "
+            f"Description: {description.strip() or 'n/a'}. "
+            f"Tags: {resolved_tags or 'n/a'}."
+        ),
+        f"MM{media_id}",
+        resolved_title,
+        domain.strip(),
+    )
+    row = conn.execute("SELECT * FROM media_memories WHERE id = ?", (media_id,)).fetchone()
+    return _row_to_dict(row)
+
+
+def get_media_memory(media_id: int) -> dict | None:
+    init_tables()
+    row = get_db().execute("SELECT * FROM media_memories WHERE id = ?", (media_id,)).fetchone()
+    return _row_to_dict(row) if row else None
+
+
+def search_media_memories(
+    *,
+    query: str = "",
+    media_type: str = "",
+    domain: str = "",
+    tag: str = "",
+    limit: int = 20,
+) -> list[dict]:
+    init_tables()
+    conditions = ["1=1"]
+    params: list = []
+    if media_type.strip():
+        conditions.append("media_type = ?")
+        params.append(media_type.strip().lower())
+    if domain.strip():
+        conditions.append("domain = ?")
+        params.append(domain.strip())
+    if tag.strip():
+        conditions.append("LOWER(tags) LIKE ?")
+        params.append(f"%{tag.strip().lower()}%")
+    if query.strip():
+        conditions.append(
+            "(LOWER(title) LIKE ? OR LOWER(description) LIKE ? OR LOWER(tags) LIKE ? OR LOWER(file_path) LIKE ? OR LOWER(url) LIKE ?)"
+        )
+        q = f"%{query.strip().lower()}%"
+        params.extend([q, q, q, q, q])
+    rows = get_db().execute(
+        f"""
+        SELECT * FROM media_memories
+         WHERE {' AND '.join(conditions)}
+         ORDER BY updated_at DESC, created_at DESC
+         LIMIT ?
+        """,
+        params + [max(1, int(limit or 20))],
+    ).fetchall()
+    return [_row_to_dict(row) for row in rows]
+
+
+def list_media_memories(limit: int = 20) -> list[dict]:
+    return search_media_memories(limit=limit)
+
+
+def media_memory_stats() -> dict:
+    init_tables()
+    conn = get_db()
+    total = int(conn.execute("SELECT COUNT(*) FROM media_memories").fetchone()[0])
+    by_type = {
+        row["media_type"]: row["cnt"]
+        for row in conn.execute(
+            "SELECT media_type, COUNT(*) AS cnt FROM media_memories GROUP BY media_type"
+        ).fetchall()
+    }
+    by_domain = {
+        row["domain"]: row["cnt"]
+        for row in conn.execute(
+            "SELECT domain, COUNT(*) AS cnt FROM media_memories WHERE domain != '' GROUP BY domain ORDER BY cnt DESC LIMIT 10"
+        ).fetchall()
+    }
+    return {
+        "total": total,
+        "by_type": by_type,
+        "by_domain": by_domain,
+        "backend": get_backend().key,
+    }

package/src/memory_backends.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+"""Explicit backend registry for memory expansion layers.
+
+NEXO's historical memory system is still heavily SQLite-shaped, but newer layers
+should not keep backend assumptions implicit forever. This module introduces a
+small registry/contract that expansion surfaces can use today while SQLite
+remains the default backend.
+"""
+
+from dataclasses import dataclass
+import os
+
+
+@dataclass(frozen=True)
+class MemoryBackendInfo:
+    key: str
+    label: str
+    description: str
+    supports: tuple[str, ...]
+    maturity: str = "stable"
+
+
+_REGISTRY: dict[str, MemoryBackendInfo] = {}
+
+
+def register_backend(info: MemoryBackendInfo) -> None:
+    _REGISTRY[info.key] = info
+
+
+def active_backend_key() -> str:
+    return (os.environ.get("NEXO_MEMORY_BACKEND", "sqlite") or "sqlite").strip().lower()
+
+
+def get_backend(key: str = "") -> MemoryBackendInfo:
+    selected = (key or active_backend_key()).strip().lower()
+    return _REGISTRY.get(selected, _REGISTRY["sqlite"])
+
+
+def list_backends() -> list[dict]:
+    active = active_backend_key()
+    results = []
+    for key in sorted(_REGISTRY):
+        info = _REGISTRY[key]
+        item = {
+            "key": info.key,
+            "label": info.label,
+            "description": info.description,
+            "supports": list(info.supports),
+            "maturity": info.maturity,
+            "active": info.key == active,
+        }
+        results.append(item)
+    return results
+
+
+register_backend(
+    MemoryBackendInfo(
+        key="sqlite",
+        label="SQLite + FTS5",
+        description="Local-first default backend used by NEXO runtime surfaces.",
+        supports=(
+            "cognitive_core",
+            "claims",
+            "media_memory",
+            "user_state",
+            "memory_export",
+            "auto_flush",
+        ),
+    )
+)

package/src/plugins/claims_tools.py

@@ -0,0 +1,119 @@
+"""Claims/wiki plugin — public surface over NEXO claim graph."""
+
+import claim_graph
+
+
+def handle_claim_add(
+    text: str,
+    domain: str = "",
+    evidence: str = "",
+    confidence: float = 1.0,
+    source_type: str = "",
+    source_id: str = "",
+    freshness_days: int = 30,
+) -> str:
+    result = claim_graph.add_claim(
+        text=text,
+        domain=domain,
+        evidence=evidence,
+        confidence=confidence,
+        source_type=source_type,
+        source_id=source_id,
+        freshness_days=freshness_days,
+    )
+    if result.get("error"):
+        return f"ERROR: {result['error']}"
+    return f"Claim #{result['id']} {result['action']} (confidence={result['confidence']})"
+
+
+def handle_claim_search(query: str = "", domain: str = "", status: str = "", limit: int = 20) -> str:
+    items = claim_graph.search_claims(query=query, domain=domain, status=status, limit=limit)
+    if not items:
+        return "No claims found."
+    lines = [f"CLAIMS — {len(items)} result(s):", ""]
+    for item in items:
+        lines.append(
+            f"  #{item['id']} [{item.get('verification_status','unverified')}] "
+            f"freshness={item.get('freshness_state','?')}({item.get('freshness_score',0)})"
+        )
+        lines.append(f"    {item['text'][:220]}")
+        if item.get("evidence"):
+            lines.append(f"    evidence: {str(item['evidence'])[:180]}")
+        if item.get("domain"):
+            lines.append(f"    domain: {item['domain']}")
+    return "\n".join(lines)
+
+
+def handle_claim_get(claim_id: int) -> str:
+    item = claim_graph.get_claim(claim_id)
+    if not item:
+        return f"Claim #{claim_id} not found."
+    lines = [
+        f"CLAIM #{item['id']}",
+        f"  status: {item.get('verification_status', 'unverified')}",
+        f"  confidence: {item.get('confidence', 0)}",
+        f"  freshness: {item.get('freshness_state', '?')} ({item.get('freshness_score', 0)})",
+        f"  age_days: {item.get('age_days', 0)}",
+        f"  domain: {item.get('domain', '') or 'n/a'}",
+        f"  source: {item.get('source_type', '')}:{item.get('source_id', '')}",
+        f"  text: {item.get('text', '')}",
+    ]
+    if item.get("evidence"):
+        lines.append(f"  evidence: {item['evidence']}")
+    if item.get("links_out"):
+        lines.append(f"  links_out: {len(item['links_out'])}")
+    if item.get("links_in"):
+        lines.append(f"  links_in: {len(item['links_in'])}")
+    return "\n".join(lines)
+
+
+def handle_claim_link(source_claim_id: int, target_claim_id: int, relation: str, confidence: float = 1.0) -> str:
+    result = claim_graph.link_claims(source_claim_id, target_claim_id, relation, confidence=confidence)
+    if result.get("error"):
+        return f"ERROR: {result['error']}"
+    return f"Linked claim #{source_claim_id} -> #{target_claim_id} [{relation}]"
+
+
+def handle_claim_verify(claim_id: int, status: str = "confirmed") -> str:
+    result = claim_graph.verify_claim(claim_id, status=status)
+    if result.get("error"):
+        return f"ERROR: {result['error']}"
+    return (
+        f"Claim #{result['id']} now {result['verification_status']} "
+        f"(freshness={result.get('freshness_state', '?')} {result.get('freshness_score', 0)})"
+    )
+
+
+def handle_claim_lint(max_age_days: int = 30, limit: int = 20) -> str:
+    items = claim_graph.lint_claims(max_age_days=max_age_days, limit=limit)
+    if not items:
+        return "Claim lint: no attention items."
+    lines = [f"CLAIM LINT — {len(items)} attention item(s):", ""]
+    for item in items:
+        lines.append(f"  #{item['id']} [{', '.join(item.get('lint_reasons', []))}]")
+        lines.append(f"    {item['text'][:220]}")
+    return "\n".join(lines)
+
+
+def handle_claim_stats() -> str:
+    stats = claim_graph.stats()
+    return (
+        "CLAIM GRAPH STATS\n"
+        f"  total: {stats['total_claims']}\n"
+        f"  links: {stats['total_links']}\n"
+        f"  contradictions: {stats['contradictions']}\n"
+        f"  lint_attention: {stats['lint_attention']}\n"
+        f"  by_status: {stats['by_status']}\n"
+        f"  by_domain: {stats['by_domain']}"
+    )
+
+
+TOOLS = [
+    (handle_claim_add, "nexo_claim_add", "Add a structured claim with provenance, evidence, and freshness."),
+    (handle_claim_search, "nexo_claim_search", "Search claims by meaning or filters."),
+    (handle_claim_get, "nexo_claim_get", "Get a single claim with its links and freshness metadata."),
+    (handle_claim_link, "nexo_claim_link", "Link two claims with supports/contradicts/refines/supersedes."),
+    (handle_claim_verify, "nexo_claim_verify", "Verify or reclassify a claim state."),
+    (handle_claim_lint, "nexo_claim_lint", "Audit stale, weak, contradictory, or evidence-poor claims."),
+    (handle_claim_stats, "nexo_claim_stats", "Claim graph statistics and attention counts."),
+]

package/src/plugins/cognitive_memory.py

@@ -21,6 +21,10 @@ def handle_cognitive_retrieve(
     include_archived: bool = False,
     use_hyde: bool | None = None,
     spreading_depth: int | None = None,
+    hybrid_alpha: float = 0.6,
+    decompose: bool = True,
+    exclude_dreams: bool = True,
+    exclude_dormant: bool = True,
 ) -> str:
     """RAG query over cognitive memory (STM + LTM). Triggers rehearsal on retrieved memories.
 
@@ -34,6 +38,10 @@ def handle_cognitive_retrieve(
         include_archived: If True, also search archived memories (default False)
         use_hyde: If True/False, force HyDE on/off. If omitted, NEXO auto-enables it for conceptual queries.
         spreading_depth: If >0, boost co-activated neighbors directly. If omitted, NEXO may auto-enable shallow spreading for multi-hop queries.
+        hybrid_alpha: Weight for vector vs BM25 fusion (default 0.6)
+        decompose: If True, decompose complex queries into sub-queries (default True)
+        exclude_dreams: If True, exclude dream insights from retrieval by default
+        exclude_dormant: If True, keep dormant LTM out of results unless explicitly requested
     """
     if not query or not query.strip():
         return "ERROR: query is required."
@@ -43,12 +51,15 @@ def handle_cognitive_retrieve(
         top_k=top_k,
         min_score=min_score,
         stores=stores,
-        exclude_dormant=True,
+        exclude_dormant=exclude_dormant,
         rehearse=True,
         source_type_filter=source_type,
         include_archived=include_archived,
         use_hyde=use_hyde,
         spreading_depth=spreading_depth,
+        hybrid_alpha=hybrid_alpha,
+        decompose=decompose,
+        exclude_dreams=exclude_dreams,
     )
 
     # Apply domain filter post-search (cognitive.search doesn't filter by domain natively)
@@ -65,6 +76,10 @@ def handle_cognitive_retrieve(
         mode_parts.append(f"spreading={spreading_depth}")
     elif spreading_depth is None:
         mode_parts.append("spreading=AUTO")
+    mode_parts.append(f"hybrid_alpha={hybrid_alpha}")
+    mode_parts.append(f"decompose={'ON' if decompose else 'OFF'}")
+    mode_parts.append(f"dreams={'OFF' if exclude_dreams else 'ON'}")
+    mode_parts.append(f"dormant={'OFF' if exclude_dormant else 'ON'}")
     if results:
         top_score = float(results[0].get("score", 0.0) or 0.0)
         confidence = "high" if top_score >= 0.82 else "medium" if top_score >= 0.66 else "low"

package/src/plugins/media_memory_tools.py

@@ -0,0 +1,98 @@
+"""Multimodal memory reference tools."""
+
+import media_memory
+
+
+def handle_media_memory_add(
+    file_path: str = "",
+    url: str = "",
+    title: str = "",
+    description: str = "",
+    tags: str = "",
+    domain: str = "",
+    source_type: str = "",
+    source_id: str = "",
+    metadata: str = "",
+) -> str:
+    result = media_memory.add_media_memory(
+        file_path=file_path,
+        url=url,
+        title=title,
+        description=description,
+        tags=tags,
+        domain=domain,
+        source_type=source_type,
+        source_id=source_id,
+        metadata=metadata,
+    )
+    if result.get("error"):
+        return f"ERROR: {result['error']}"
+    location = result.get("file_path") or result.get("url") or "n/a"
+    return f"Media memory #{result['id']} [{result['media_type']}] stored: {location}"
+
+
+def handle_media_memory_search(
+    query: str = "",
+    media_type: str = "",
+    domain: str = "",
+    tag: str = "",
+    limit: int = 20,
+) -> str:
+    items = media_memory.search_media_memories(
+        query=query,
+        media_type=media_type,
+        domain=domain,
+        tag=tag,
+        limit=limit,
+    )
+    if not items:
+        return "No media memories found."
+    lines = [f"MEDIA MEMORIES — {len(items)} result(s):", ""]
+    for item in items:
+        lines.append(f"  #{item['id']} [{item['media_type']}] {item['title'][:120]}")
+        lines.append(f"    {item.get('file_path') or item.get('url') or 'n/a'}")
+        if item.get("description"):
+            lines.append(f"    {item['description'][:180]}")
+        if item.get("tags"):
+            lines.append(f"    tags: {item['tags']}")
+    return "\n".join(lines)
+
+
+def handle_media_memory_get(media_id: int) -> str:
+    item = media_memory.get_media_memory(media_id)
+    if not item:
+        return f"Media memory #{media_id} not found."
+    lines = [
+        f"MEDIA MEMORY #{item['id']}",
+        f"  type: {item['media_type']}",
+        f"  title: {item['title']}",
+        f"  location: {item.get('file_path') or item.get('url') or 'n/a'}",
+        f"  domain: {item.get('domain') or 'n/a'}",
+        f"  source: {item.get('source_type') or 'n/a'}:{item.get('source_id') or ''}",
+    ]
+    if item.get("description"):
+        lines.append(f"  description: {item['description']}")
+    if item.get("tags"):
+        lines.append(f"  tags: {item['tags']}")
+    if item.get("metadata"):
+        lines.append(f"  metadata: {item['metadata']}")
+    return "\n".join(lines)
+
+
+def handle_media_memory_stats() -> str:
+    stats = media_memory.media_memory_stats()
+    return (
+        "MEDIA MEMORY STATS\n"
+        f"  total: {stats['total']}\n"
+        f"  backend: {stats['backend']}\n"
+        f"  by_type: {stats['by_type']}\n"
+        f"  by_domain: {stats['by_domain']}"
+    )
+
+
+TOOLS = [
+    (handle_media_memory_add, "nexo_media_memory_add", "Store a non-text artifact as first-class media memory metadata."),
+    (handle_media_memory_search, "nexo_media_memory_search", "Search media memories by text, type, tag, or domain."),
+    (handle_media_memory_get, "nexo_media_memory_get", "Inspect one stored media memory."),
+    (handle_media_memory_stats, "nexo_media_memory_stats", "Stats for the multimodal/media memory layer."),
+]