memuron 0.1.1__py3-none-any.whl

memuron/ingest/prompts.py

@@ -0,0 +1,147 @@
+"""Guardian prompts and structured output schemas."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+PROMPT_VERSION = "3.1"
+
+SPACE_GUARDIAN_SECTION = """
+SPACE CONTEXT
+Active space: {active_space_name} ({active_space_token})
+Space contract (what belongs here):
+{active_space_prompt}
+
+Other registered spaces (one-line summaries):
+{other_spaces_summary}
+
+Registered space tokens (pick from this list only):
+{registered_tokens}
+
+All registered spaces (name, token, contract):
+{all_spaces_detail}
+
+SPACE RULES — mode: {space_mode}
+- Each memory belongs to exactly ONE `space.*` token unless the user content explicitly requires two (rare). Default: pick the single best-matching space.
+- STRICT (user explicitly picked a space): MUST use `{active_space_token}` as the only space token unless the user text clearly spans two spaces.
+- ASSIST (session default / no explicit pick): Choose the single best enabled `space.*` token. The hint space is a default only — route elsewhere when the contract fits better.
+- Never tag all enabled spaces on one memory. Never invent tokens outside the registered list.
+- Apply the active space contract for linking style when the memory belongs there.
+"""
+
+MEMORY_WRITE_GUARDIAN_PROMPT = """You are the Guardian of the memory system.
+
+Produce a COMPLETE write plan for one new memory input in a single pass.
+Return ONLY valid JSON. No markdown. No extra commentary.
+
+INPUT
+New content:
+{new_content}
+
+Candidate memories (with semantic similarity scores):
+{candidates_text}
+
+If there are no candidates, treat this as an empty list.
+
+DECISION RULES
+- Choose `update` only if the new content is about the SAME specific memory and mainly expands, corrects, or refines it.
+- Choose `create` if the new content is a distinct memory, even if it is related.
+- NEVER choose `update` when the target candidate is an image, document, or collection node (`node_type` ≠ text). Link to those nodes instead; text ingest must not rewrite media/collection records.
+- Prefer granular memories over monolithic ones.
+- Similarity scores are hints only.
+
+MEMORY SHAPING RULES
+- `final_content` should be concise, coherent, natural, and information-dense.
+- If `action` is `update`, `final_content` must already be the merged final memory text.
+- If information conflicts and `update` is correct, prefer newer information while keeping the memory coherent.
+- Extract unified `scope` (5-12 strings) from `final_content` for classification and filtering.
+
+GRAPH ACTION RULES
+- You may propose up to 2 meaningful graph links to candidate memories.
+- Only link when there is clear causal, same-entity, dependency, continuation, or topic-deepening value.
+- Do not link for shallow token overlap.
+- Each link `description` must be 2-3 natural questions and should contain question marks.
+- You may also propose stale links to remove using `links_to_remove`.
+- Do not propose neighbor scope rewrites in this prompt.
+
+JSON SCHEMA
+{{
+  "action": "create" | "update",
+  "target_memory_id": "candidate id when action=update, otherwise null",
+  "reasoning": "brief explanation",
+  "final_content": "canonical memory text",
+  "scope": ["token1", "token2"],
+  "connections": [
+    {{"target_id": "candidate id", "description": "2-3 questions connecting the memories?"}}
+  ],
+  "links_to_remove": [["memory_id_1", "memory_id_2"]]
+}}
+"""
+
+
+class ConnectionSpec(BaseModel):
+    target_id: str
+    description: str
+
+
+class GuardianWritePlan(BaseModel):
+    action: Literal["create", "update"]
+    target_memory_id: str | None = None
+    reasoning: str
+    final_content: str
+    scope: list[str] = Field(default_factory=list)
+    connections: list[ConnectionSpec] = Field(default_factory=list)
+    links_to_remove: list[list[str]] = Field(default_factory=list)
+
+
+DOCUMENT_LINK_GUARDIAN_PROMPT = """You are the Guardian linking a newly ingested document into an existing memory graph.
+
+You receive:
+1. EXTERNAL CANDIDATES — up to 30 existing memories (retrieved by embedding similarity across chunks).
+2. IN-DOCUMENT MEMORIES — chunks and image nodes from this ingest (chunks may link to each other or to images).
+3. Optional vision attachments for image nodes (when provided).
+
+TASK
+For EACH in-document chunk listed below, propose 0, 1, or 2 OUTGOING semantic links.
+- Links may target EXTERNAL CANDIDATES or other IN-DOCUMENT memories (chunks or images).
+- Do NOT link to the collection node or the document source node.
+- Only link when there is clear topical, causal, dependency, continuation, or deepening value.
+- Do not link for shallow overlap.
+- Each link description must be 2-3 natural questions and must contain question marks.
+
+Return ONLY valid JSON matching the schema. No markdown.
+
+IN-DOCUMENT CHUNKS
+{chunks_text}
+
+IN-DOCUMENT IMAGES
+{images_text}
+
+EXTERNAL CANDIDATES
+{external_text}
+
+JSON SCHEMA
+{{
+  "reasoning": "brief overall strategy",
+  "chunk_links": [
+    {{
+      "chunk_id": "chunk memory id",
+      "connections": [
+        {{"target_id": "allowed target id", "description": "2-3 questions?"}}
+      ]
+    }}
+  ]
+}}
+"""
+
+
+class ChunkLinkAssignment(BaseModel):
+    chunk_id: str
+    connections: list[ConnectionSpec] = Field(default_factory=list)
+
+
+class DocumentLinkGuardianPlan(BaseModel):
+    reasoning: str = ""
+    chunk_links: list[ChunkLinkAssignment] = Field(default_factory=list)

memuron/memory/__init__.py

@@ -0,0 +1 @@
+"""Memory event recipes, projections, and Artha engine adapter."""

memuron/memory/engine.py

@@ -0,0 +1,35 @@
+"""Memuron-specific ArthaEngine extensions."""
+
+from __future__ import annotations
+
+from urllib.parse import urlparse, urlunparse
+
+from artha_engine import ArthaEngine
+from artha_engine.store import is_postgres_dsn
+
+
+def mask_database_url(url: str) -> str:
+    if not url:
+        return url
+    if is_postgres_dsn(url):
+        parsed = urlparse(url)
+        host = parsed.hostname or ""
+        if parsed.port:
+            host = f"{host}:{parsed.port}"
+        if parsed.username:
+            netloc = f"{parsed.username}:***@{host}"
+        else:
+            netloc = f"***@{host}" if host else "***"
+        return urlunparse(
+            (parsed.scheme, netloc, parsed.path, parsed.params, parsed.query, parsed.fragment)
+        )
+    return url
+
+
+class MemuronArthaEngine(ArthaEngine):
+    def runtime_summary(self, *, profiles: list[str] | None = None) -> dict[str, object]:
+        summary = super().runtime_summary(profiles=profiles)
+        db_path = summary.get("db_path")
+        if db_path is not None:
+            summary = {**summary, "db_path": mask_database_url(str(db_path))}
+        return summary

memuron/memory/projections.py

@@ -0,0 +1,452 @@
+"""Memuron read-model projections."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from artha_engine.store.projection_sql import sql_store_execute, sql_store_fetchall, sql_store_has_tables
+
+from memuron.application.config import settings
+
+
+def _json_dumps(value: object) -> str:
+    return json.dumps(value, ensure_ascii=True)
+
+
+def _json_loads(value: object, default: object) -> object:
+    if value is None:
+        return default
+    if isinstance(value, (list, dict)):
+        return value
+    try:
+        return json.loads(str(value))
+    except json.JSONDecodeError:
+        return default
+
+
+def _drop_legacy_category_column(store: Any) -> None:
+    if not sql_store_has_tables(store):
+        return
+    try:
+        sql_store_execute(store, "ALTER TABLE memuron_memories DROP COLUMN category")
+    except Exception:
+        pass
+
+
+def _add_column_if_missing(store: Any, table: str, column_sql: str) -> None:
+    if not sql_store_has_tables(store):
+        return
+    try:
+        sql_store_execute(store, f"ALTER TABLE {table} ADD COLUMN {column_sql}")
+    except Exception:
+        pass
+
+
+class MemoryProjection:
+    name = "memuron_memories"
+
+    def init(self, store: Any) -> None:
+        if not sql_store_has_tables(store):
+            store.memuron_memories = getattr(store, "memuron_memories", {})
+            return
+        sql_store_execute(
+            store,
+            """
+            CREATE TABLE IF NOT EXISTS memuron_memories (
+              artha_id TEXT PRIMARY KEY,
+              content TEXT NOT NULL,
+              node_type TEXT NOT NULL DEFAULT 'text',
+              payload_json TEXT NOT NULL DEFAULT '{}',
+              perception TEXT,
+              encoding TEXT NOT NULL DEFAULT 'memory',
+              metadata_json TEXT NOT NULL DEFAULT '{}',
+              scope_json TEXT NOT NULL DEFAULT '[]',
+              embedding_json TEXT NOT NULL DEFAULT '[]',
+              created_at TEXT,
+              updated_at TEXT,
+              sequence BIGINT NOT NULL DEFAULT 0
+            )
+            """,
+        )
+        _drop_legacy_category_column(store)
+        _add_column_if_missing(store, "memuron_memories", "node_type TEXT NOT NULL DEFAULT 'text'")
+        _add_column_if_missing(store, "memuron_memories", "payload_json TEXT NOT NULL DEFAULT '{}'")
+        _add_column_if_missing(store, "memuron_memories", "perception TEXT")
+        _add_column_if_missing(store, "memuron_memories", "encoding TEXT NOT NULL DEFAULT 'memory'")
+        _add_column_if_missing(store, "memuron_memories", "metadata_json TEXT NOT NULL DEFAULT '{}'")
+        from memuron.search.fulltext import ensure_fulltext_schema
+        from memuron.search.pgvector import ensure_pgvector_schema
+
+        ensure_pgvector_schema(store, settings.vector_dimensions)
+        ensure_fulltext_schema(store)
+
+    def apply(self, event: dict[str, object], store: Any) -> None:
+        event_type = str(event.get("event_type", ""))
+        if event_type in {"delete", "memory.deleted"}:
+            if event.get("subject_type") == "memory":
+                self._delete(str(event["subject_id"]), store)
+            return
+        if event_type not in {"memory.created", "memory.updated", "collection.created"}:
+            return
+        payload = event.get("payload")
+        if not isinstance(payload, dict):
+            return
+        arthaanu = payload.get("arthaanu")
+        if not isinstance(arthaanu, dict):
+            return
+        value = arthaanu.get("value")
+        if not isinstance(value, dict):
+            return
+        content = value.get("content")
+        if not isinstance(content, str):
+            return
+        scope = _json_loads(value.get("scope"), [])
+        embedding = _json_loads(value.get("embedding"), [])
+        node_type = str(value.get("node_type") or "text")
+        payload_json = _json_dumps(_json_loads(value.get("payload"), {}))
+        perception = value.get("perception")
+        encoding = str(value.get("encoding") or "memory")
+        metadata_json = _json_dumps(_json_loads(value.get("metadata"), {}))
+        artha_id = str(event["subject_id"])
+        sequence = int(event["sequence"])
+        metadata = event.get("metadata")
+        created_at = None
+        if isinstance(metadata, dict):
+            created_at = metadata.get("created_at")
+        if sql_store_has_tables(store):
+            existing = sql_store_fetchall(
+                store,
+                "SELECT created_at FROM memuron_memories WHERE artha_id = ?",
+                (artha_id,),
+            )
+            if existing and existing[0].get("created_at"):
+                created_at = existing[0]["created_at"]
+            sql_store_execute(
+                store,
+                """
+                INSERT INTO memuron_memories (
+                  artha_id, content, node_type, payload_json, perception, encoding, metadata_json,
+                  scope_json, embedding_json,
+                  created_at, updated_at, sequence
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                ON CONFLICT(artha_id) DO UPDATE SET
+                  content = excluded.content,
+                  node_type = excluded.node_type,
+                  payload_json = excluded.payload_json,
+                  perception = excluded.perception,
+                  encoding = excluded.encoding,
+                  metadata_json = excluded.metadata_json,
+                  scope_json = excluded.scope_json,
+                  embedding_json = excluded.embedding_json,
+                  updated_at = excluded.updated_at,
+                  sequence = excluded.sequence
+                """,
+                (
+                    artha_id,
+                    content,
+                    node_type,
+                    payload_json,
+                    perception if isinstance(perception, str) else None,
+                    encoding,
+                    metadata_json,
+                    _json_dumps(scope if isinstance(scope, list) else []),
+                    _json_dumps(embedding if isinstance(embedding, list) else []),
+                    created_at or str(event.get("created_at", "")),
+                    str(event.get("created_at", "")),
+                    sequence,
+                ),
+            )
+            from memuron.search.fulltext import sync_memory_fulltext
+            from memuron.search.pgvector import sync_memory_embedding
+
+            sync_memory_embedding(
+                store,
+                artha_id,
+                [float(value) for value in embedding] if isinstance(embedding, list) else [],
+            )
+            sync_memory_fulltext(store, artha_id, content)
+        else:
+            bucket = store.memuron_memories
+            prior = bucket.get(artha_id, {})
+            bucket[artha_id] = {
+                "content": content,
+                "node_type": node_type,
+                "payload": _json_loads(value.get("payload"), {}),
+                "perception": perception if isinstance(perception, str) else None,
+                "encoding": encoding,
+                "metadata": _json_loads(value.get("metadata"), {}),
+                "scope": scope if isinstance(scope, list) else [],
+                "embedding": embedding if isinstance(embedding, list) else [],
+                "created_at": prior.get("created_at") or str(event.get("created_at", "")),
+                "updated_at": str(event.get("created_at", "")),
+                "sequence": sequence,
+            }
+
+    def reset(self, store: Any) -> None:
+        if sql_store_has_tables(store):
+            sql_store_execute(store, "DELETE FROM memuron_memories")
+        else:
+            store.memuron_memories = {}
+
+    def _delete(self, artha_id: str, store: Any) -> None:
+        if sql_store_has_tables(store):
+            sql_store_execute(
+                store,
+                "DELETE FROM memuron_memories WHERE artha_id = ?",
+                (artha_id,),
+            )
+        else:
+            store.memuron_memories.pop(artha_id, None)
+
+
+class MemoryLinkProjection:
+    name = "memuron_links"
+
+    def init(self, store: Any) -> None:
+        if not sql_store_has_tables(store):
+            store.memuron_links = getattr(store, "memuron_links", {})
+            return
+        sql_store_execute(
+            store,
+            """
+            CREATE TABLE IF NOT EXISTS memuron_links (
+              link_id TEXT PRIMARY KEY,
+              source_id TEXT NOT NULL,
+              target_id TEXT NOT NULL,
+              description TEXT NOT NULL,
+              metadata_json TEXT NOT NULL DEFAULT '{}',
+              embedding_json TEXT NOT NULL DEFAULT '[]',
+              sequence BIGINT NOT NULL DEFAULT 0
+            )
+            """,
+        )
+        _add_column_if_missing(store, "memuron_links", "metadata_json TEXT NOT NULL DEFAULT '{}'")
+        sql_store_execute(
+            store,
+            "CREATE INDEX IF NOT EXISTS idx_memuron_links_source ON memuron_links(source_id)",
+        )
+        sql_store_execute(
+            store,
+            "CREATE INDEX IF NOT EXISTS idx_memuron_links_target ON memuron_links(target_id)",
+        )
+
+    def apply(self, event: dict[str, object], store: Any) -> None:
+        event_type = str(event.get("event_type", ""))
+        if event_type == "delete" and event.get("subject_type") == "memory_link":
+            # Legacy replay only — new writes use link.removed.
+            self._delete(str(event["subject_id"]), store)
+            return
+        if event_type not in {"link.created", "link.removed"}:
+            return
+        if event_type == "link.removed":
+            link_id = str(event.get("subject_id", ""))
+            payload = event.get("payload")
+            if isinstance(payload, dict) and payload.get("link_id"):
+                link_id = str(payload["link_id"])
+            if link_id:
+                self._delete(link_id, store)
+            return
+        payload = event.get("payload")
+        if not isinstance(payload, dict):
+            return
+        arthaanu = payload.get("arthaanu")
+        if not isinstance(arthaanu, dict):
+            return
+        value = arthaanu.get("value")
+        if not isinstance(value, dict):
+            return
+        source_id = value.get("source_id")
+        target_id = value.get("target_id")
+        description = value.get("description")
+        if not isinstance(source_id, str) or not isinstance(target_id, str):
+            return
+        if not isinstance(description, str):
+            return
+        metadata = _json_loads(value.get("metadata"), {})
+        embedding = _json_loads(value.get("embedding"), [])
+        link_id = str(event["subject_id"])
+        sequence = int(event["sequence"])
+        if sql_store_has_tables(store):
+            sql_store_execute(
+                store,
+                """
+                INSERT INTO memuron_links (
+                  link_id, source_id, target_id, description, metadata_json, embedding_json, sequence
+                ) VALUES (?, ?, ?, ?, ?, ?, ?)
+                ON CONFLICT(link_id) DO UPDATE SET
+                  source_id = excluded.source_id,
+                  target_id = excluded.target_id,
+                  description = excluded.description,
+                  metadata_json = excluded.metadata_json,
+                  embedding_json = excluded.embedding_json,
+                  sequence = excluded.sequence
+                """,
+                (
+                    link_id,
+                    source_id,
+                    target_id,
+                    description,
+                    _json_dumps(metadata if isinstance(metadata, dict) else {}),
+                    _json_dumps(embedding if isinstance(embedding, list) else []),
+                    sequence,
+                ),
+            )
+            from memuron.search.pgvector import sync_link_embedding
+
+            sync_link_embedding(
+                store,
+                link_id,
+                [float(value) for value in embedding] if isinstance(embedding, list) else [],
+            )
+        else:
+            store.memuron_links[link_id] = {
+                "source_id": source_id,
+                "target_id": target_id,
+                "description": description,
+                "metadata": metadata if isinstance(metadata, dict) else {},
+                "embedding": embedding if isinstance(embedding, list) else [],
+                "sequence": sequence,
+            }
+
+    def reset(self, store: Any) -> None:
+        if sql_store_has_tables(store):
+            sql_store_execute(store, "DELETE FROM memuron_links")
+        else:
+            store.memuron_links = {}
+
+    def _delete(self, link_id: str, store: Any) -> None:
+        if sql_store_has_tables(store):
+            sql_store_execute(
+                store,
+                "DELETE FROM memuron_links WHERE link_id = ?",
+                (link_id,),
+            )
+        else:
+            store.memuron_links.pop(link_id, None)
+
+
+class MemoryPlacementProjection:
+    name = "memuron_placements"
+
+    def init(self, store: Any) -> None:
+        if not sql_store_has_tables(store):
+            store.memuron_placements = getattr(store, "memuron_placements", {})
+            return
+        sql_store_execute(
+            store,
+            """
+            CREATE TABLE IF NOT EXISTS memuron_placements (
+              placement_id TEXT PRIMARY KEY,
+              parent_id TEXT NOT NULL,
+              child_id TEXT NOT NULL,
+              name TEXT NOT NULL,
+              scope_json TEXT NOT NULL DEFAULT '[]',
+              metadata_json TEXT NOT NULL DEFAULT '{}',
+              inherit_parent_scope BOOLEAN NOT NULL DEFAULT TRUE,
+              sequence BIGINT NOT NULL DEFAULT 0,
+              UNIQUE(parent_id, name)
+            )
+            """,
+        )
+        _add_column_if_missing(
+            store,
+            "memuron_placements",
+            "inherit_parent_scope BOOLEAN NOT NULL DEFAULT TRUE",
+        )
+        sql_store_execute(
+            store,
+            "CREATE INDEX IF NOT EXISTS idx_memuron_placements_parent ON memuron_placements(parent_id)",
+        )
+        sql_store_execute(
+            store,
+            "CREATE INDEX IF NOT EXISTS idx_memuron_placements_child ON memuron_placements(child_id)",
+        )
+
+    def apply(self, event: dict[str, object], store: Any) -> None:
+        event_type = str(event.get("event_type", ""))
+        if event_type == "delete" and event.get("subject_type") == "memory_placement":
+            self._delete(str(event["subject_id"]), store)
+            return
+        if event_type not in {"placement.created", "placement.removed"}:
+            return
+        if event_type == "placement.removed":
+            placement_id = str(event.get("subject_id", ""))
+            payload = event.get("payload")
+            if isinstance(payload, dict) and payload.get("placement_id"):
+                placement_id = str(payload["placement_id"])
+            if placement_id:
+                self._delete(placement_id, store)
+            return
+        payload = event.get("payload")
+        if not isinstance(payload, dict):
+            return
+        arthaanu = payload.get("arthaanu")
+        if not isinstance(arthaanu, dict):
+            return
+        value = arthaanu.get("value")
+        if not isinstance(value, dict):
+            return
+        parent_id = value.get("parent_id")
+        child_id = value.get("child_id")
+        name = value.get("name")
+        if not isinstance(parent_id, str) or not isinstance(child_id, str) or not isinstance(name, str):
+            return
+        scope = _json_loads(value.get("scope"), [])
+        metadata = _json_loads(value.get("metadata"), {})
+        inherit_parent_scope = bool(value.get("inherit_parent_scope", True))
+        placement_id = str(event["subject_id"])
+        sequence = int(event["sequence"])
+        if sql_store_has_tables(store):
+            sql_store_execute(
+                store,
+                """
+                INSERT INTO memuron_placements (
+                  placement_id, parent_id, child_id, name, scope_json, metadata_json,
+                  inherit_parent_scope, sequence
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+                ON CONFLICT(parent_id, name) DO UPDATE SET
+                  placement_id = excluded.placement_id,
+                  child_id = excluded.child_id,
+                  scope_json = excluded.scope_json,
+                  metadata_json = excluded.metadata_json,
+                  inherit_parent_scope = excluded.inherit_parent_scope,
+                  sequence = excluded.sequence
+                """,
+                (
+                    placement_id,
+                    parent_id,
+                    child_id,
+                    name,
+                    _json_dumps(scope if isinstance(scope, list) else []),
+                    _json_dumps(metadata if isinstance(metadata, dict) else {}),
+                    inherit_parent_scope,
+                    sequence,
+                ),
+            )
+        else:
+            store.memuron_placements[placement_id] = {
+                "parent_id": parent_id,
+                "child_id": child_id,
+                "name": name,
+                "scope": scope if isinstance(scope, list) else [],
+                "metadata": metadata if isinstance(metadata, dict) else {},
+                "inherit_parent_scope": inherit_parent_scope,
+                "sequence": sequence,
+            }
+
+    def reset(self, store: Any) -> None:
+        if sql_store_has_tables(store):
+            sql_store_execute(store, "DELETE FROM memuron_placements")
+        else:
+            store.memuron_placements = {}
+
+    def _delete(self, placement_id: str, store: Any) -> None:
+        if sql_store_has_tables(store):
+            sql_store_execute(
+                store,
+                "DELETE FROM memuron_placements WHERE placement_id = ?",
+                (placement_id,),
+            )
+        else:
+            store.memuron_placements.pop(placement_id, None)