dreaming-memory 0.2.0__py3-none-any.whl

dreaming_memory/__init__.py

@@ -0,0 +1,18 @@
+"""Agent-agnostic memory extension — Postgres-backed agent memory."""
+
+from dreaming_memory.agent_memory import AgentMemory
+from dreaming_memory.config import FleetConfig
+from dreaming_memory.session import SessionContext
+from dreaming_memory.types import MemoryRecord, MemorySource, MemoryType, SessionType
+
+__all__ = [
+    "AgentMemory",
+    "FleetConfig",
+    "MemoryRecord",
+    "MemorySource",
+    "MemoryType",
+    "SessionContext",
+    "SessionType",
+]
+
+__version__ = "0.2.0"

dreaming_memory/agent_memory.py

@@ -0,0 +1,161 @@
+"""High-level facade for agents — Postgres SSOT + optional semantic + integrations."""
+
+from __future__ import annotations
+
+from typing import Any
+from uuid import UUID
+
+from dreaming_memory.config import FleetConfig
+from dreaming_memory.integrations.cloudflare import CloudflareR2
+from dreaming_memory.integrations.linear import LinearMemoryBridge
+from dreaming_memory.integrations.notion import NotionMemoryBridge
+from dreaming_memory.observability import sentry
+from dreaming_memory.semantic.lancedb import SemanticMemoryStore
+from dreaming_memory.session import SessionContext
+from dreaming_memory.store.postgres import AgentMemoryStore
+from dreaming_memory.types import MemoryRecord, MemorySource, MemoryType, SessionType
+
+
+class AgentMemory:
+    """
+    Main entry point for agent memory within cursor-dreaming-sdk.
+
+    Usage:
+        memory = AgentMemory()
+        memory.ensure_schema()
+        ctx = SessionContext.for_dream_eval("2026-06-15T09-00-00Z")
+        memory.remember(ctx, MemoryType.OBSERVATION, {"note": "faithfulness 0.63"}, source=MemorySource.SDK)
+    """
+
+    def __init__(
+        self,
+        store: AgentMemoryStore | None = None,
+        semantic: SemanticMemoryStore | None = None,
+        linear: LinearMemoryBridge | None = None,
+        notion: NotionMemoryBridge | None = None,
+        config: FleetConfig | None = None,
+        enable_sentry: bool = True,
+    ) -> None:
+        self.config = config or FleetConfig.load()
+        self.store = store or AgentMemoryStore(self.config.database_url)
+        self.semantic = semantic
+        self._linear = linear
+        self._notion = notion
+        self._cloudflare: CloudflareR2 | None = None
+        if enable_sentry:
+            sentry.init_sentry(self.config)
+
+    def close(self) -> None:
+        self.store.close()
+
+    def __enter__(self) -> AgentMemory:
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    @property
+    def cloudflare(self) -> CloudflareR2:
+        if self._cloudflare is None:
+            self._cloudflare = CloudflareR2(self.config)
+        return self._cloudflare
+
+    def ensure_schema(self) -> None:
+        self.store.ensure_schema()
+
+    @property
+    def linear(self) -> LinearMemoryBridge:
+        if self._linear is None:
+            self._linear = LinearMemoryBridge(self.store)
+        return self._linear
+
+    @property
+    def notion(self) -> NotionMemoryBridge:
+        if self._notion is None:
+            self._notion = NotionMemoryBridge(self.store)
+        return self._notion
+
+    def remember(
+        self,
+        session: SessionContext,
+        memory_type: MemoryType,
+        content: dict[str, Any],
+        *,
+        source: MemorySource = MemorySource.SDK,
+        metadata: dict[str, Any] | None = None,
+    ) -> MemoryRecord:
+        record = MemoryRecord(
+            agent_id=session.agent_id,
+            session_id=session.session_id,
+            session_type=session.session_type,
+            memory_type=memory_type,
+            content=content,
+            source=source,
+            metadata={**(session.metadata or {}), **(metadata or {})},
+        )
+        sentry.breadcrumb(
+            f"remember {memory_type.value}",
+            data={"session_type": session.session_type.value, "source": source.value},
+        )
+        return self.store.write(record)
+
+    def recall(
+        self,
+        *,
+        agent_id: str | None = None,
+        session_id: str | None = None,
+        session_type: SessionType | None = None,
+        memory_type: MemoryType | None = None,
+        source: MemorySource | None = None,
+        limit: int = 50,
+    ) -> list[MemoryRecord]:
+        return self.store.query(
+            agent_id=agent_id,
+            session_id=session_id,
+            session_type=session_type,
+            memory_type=memory_type,
+            source=source,
+            limit=limit,
+        )
+
+    def recall_session(self, session: SessionContext, limit: int = 50) -> list[MemoryRecord]:
+        return self.recall(
+            agent_id=session.agent_id,
+            session_id=session.session_id,
+            session_type=session.session_type,
+            limit=limit,
+        )
+
+    def index_semantic(
+        self,
+        record: MemoryRecord,
+        text: str,
+        vector: list[float],
+    ) -> MemoryRecord | None:
+        if self.semantic is None:
+            raise RuntimeError("semantic store not configured — pass SemanticMemoryStore() to AgentMemory")
+        if not self.semantic.enabled:
+            return None
+        if record.id is None:
+            raise ValueError("record must have an id before indexing into semantic store")
+        self.semantic.index_memory(
+            record.id, text, vector, metadata={"source": record.source.value}
+        )
+        ref = MemoryRecord(
+            agent_id=record.agent_id,
+            session_id=record.session_id,
+            session_type=record.session_type,
+            memory_type=MemoryType.EMBEDDING_REF,
+            source=MemorySource.SDK,
+            content={"text_preview": text[:500], "parent_id": str(record.id)},
+            metadata={"lance_table": self.semantic.table_name},
+        )
+        return self.store.write(ref)
+
+    def search_semantic(self, vector: list[float], limit: int = 10) -> list[dict[str, Any]]:
+        if self.semantic is None or not self.semantic.enabled:
+            return []
+        return self.semantic.search(vector, limit=limit)
+
+    def get(self, memory_id: UUID) -> MemoryRecord | None:
+        return self.store.get(memory_id)

dreaming_memory/cli.py

@@ -0,0 +1,262 @@
+#!/usr/bin/env python3
+"""CLI for agent memory — schema init, query, Linear/Notion ingest."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from dreaming_memory import AgentMemory, FleetConfig, SessionContext
+from dreaming_memory.types import MemoryRecord, MemorySource, MemoryType, SessionType
+
+
+def _print_records(records: list[MemoryRecord]) -> None:
+    for r in records:
+        print(json.dumps(r.model_dump(mode="json"), default=str))
+
+
+def _enum_value(value: object) -> object:
+    """Return the underlying value for StrEnum members, pass others through."""
+    return value.value if hasattr(value, "value") else value
+
+
+def render_export_markdown(session_id: str, records: list[MemoryRecord]) -> str:
+    """Render memory records for a session as Markdown (pure, DB-free)."""
+    lines: list[str] = [f"# Memory export — {session_id}", ""]
+    if not records:
+        lines.append("_No memory records found._")
+        return "\n".join(lines) + "\n"
+    for r in records:
+        memory_type = _enum_value(r.memory_type)
+        source = _enum_value(r.source)
+        created = r.created_at.isoformat() if r.created_at else "unknown"
+        lines.append(f"## {memory_type} ({created})")
+        lines.append(f"**Source:** {source}")
+        lines.append("")
+        lines.append("```json")
+        lines.append(json.dumps(r.content, indent=2, default=str, ensure_ascii=False))
+        lines.append("```")
+        lines.append("")
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def _doctor() -> None:
+    """Print config presence + Postgres/Linear/Notion connectivity (no secret values)."""
+    import httpx
+    import psycopg
+
+    config = FleetConfig.load()
+    status = config.status()
+    print(json.dumps({"config": status, "redacted": config.redacted()}, indent=2))
+    try:
+        memory = AgentMemory(config=config, enable_sentry=False)
+        with memory.store._pool.connection() as conn:
+            conn.execute("SELECT 1")
+        memory.store.close()
+        print('{"postgres": "ok"}')
+    except psycopg.Error as exc:
+        print(json.dumps({"postgres": "error", "detail": str(exc)}))
+
+    if config.linear_api_key:
+        try:
+            from dreaming_memory.integrations.linear import LinearClient
+
+            client = LinearClient(api_key=config.linear_api_key)
+            client.gql("query { viewer { id } }")
+            print('{"linear": "ok"}')
+        except httpx.HTTPError as exc:
+            print(json.dumps({"linear": "error", "detail": str(exc)}))
+    else:
+        print('{"linear": "missing_api_key"}')
+
+    if config.notion_api_key:
+        try:
+            from dreaming_memory.integrations.notion import NotionMemoryBridge
+            from dreaming_memory.store.postgres import AgentMemoryStore
+
+            NotionMemoryBridge(AgentMemoryStore(config.database_url))
+            print('{"notion": "wired"}')
+        except httpx.HTTPError as exc:
+            print(json.dumps({"notion": "error", "detail": str(exc)}))
+    else:
+        print('{"notion": "missing_api_key"}')
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="cursor-dreaming-sdk agent memory CLI")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("init", help="Apply Postgres schema")
+    sub.add_parser("doctor", help="Show config presence + DB connectivity")
+
+    p_metrics = sub.add_parser("metrics", help="Print aggregated metrics as JSON")
+    p_metrics.add_argument("--days", type=int, default=14)
+
+    p_triage = sub.add_parser("triage", help="Auto-triage untriaged Linear issues")
+    p_triage.add_argument("--state", default=None, help="Filter by workflow state name")
+    p_triage.add_argument("--limit", type=int, default=50)
+    p_triage.add_argument("--apply", action="store_true", help="Write priority/labels to Linear")
+    p_triage.add_argument("--comment", action="store_true", help="Post rationale comment")
+
+    p_serve = sub.add_parser("serve", help="Run the metrics dashboard")
+    p_serve.add_argument("--host", default="0.0.0.0")
+    p_serve.add_argument("--port", type=int, default=8787)
+
+    p_remember = sub.add_parser("remember", help="Write a memory record")
+    p_remember.add_argument("--agent", default="default")
+    p_remember.add_argument("--session-id", required=True)
+    p_remember.add_argument("--session-type", default="generic")
+    p_remember.add_argument("--type", dest="memory_type", default="observation")
+    p_remember.add_argument("--source", default="sdk")
+    p_remember.add_argument("--content", required=True, help="JSON object")
+
+    p_recall = sub.add_parser("recall", help="Query memory records")
+    p_recall.add_argument("--agent")
+    p_recall.add_argument("--session-id")
+    p_recall.add_argument("--session-type")
+    p_recall.add_argument("--type", dest="memory_type")
+    p_recall.add_argument("--source")
+    p_recall.add_argument("--limit", type=int, default=20)
+
+    p_linear = sub.add_parser("linear-ingest", help="Ingest Linear issue into memory")
+    p_linear.add_argument("issue_id")
+    p_linear.add_argument("--session-id", default="linear-sync")
+    p_linear.add_argument("--session-type", default="cursor")
+
+    p_notion = sub.add_parser("notion-ingest", help="Ingest Notion page into memory")
+    p_notion.add_argument("page_id")
+    p_notion.add_argument("--session-id", default="notion-sync")
+    p_notion.add_argument("--session-type", default="cursor")
+
+    p_export = sub.add_parser("export", help="Export a session's memory as Markdown")
+    p_export.add_argument("--session-id", required=True)
+    p_export.add_argument("--agent", default=None)
+    p_export.add_argument("--output", default=None, help="Write Markdown to this file")
+
+    p_slack = sub.add_parser("slack-report", help="Post an eval report to Slack")
+    p_slack.add_argument("--run-id", default=None)
+    p_slack.add_argument("--metrics-json", default=None, help="Path to metrics JSON file")
+
+    args = parser.parse_args()
+
+    if args.command == "doctor":
+        _doctor()
+        return
+
+    if args.command == "metrics":
+        from dreaming_memory.store.postgres import AgentMemoryStore
+
+        with AgentMemoryStore() as store:
+            print(json.dumps(store.metrics(days=args.days), indent=2, default=str))
+        return
+
+    if args.command == "serve":
+        from dreaming_memory.dashboard import serve
+
+        serve(host=args.host, port=args.port)
+        return
+
+    if args.command == "triage":
+        from dreaming_memory.triage import AutoTriage
+
+        with AutoTriage() as triage:
+            results = triage.run(
+                state=args.state, limit=args.limit, apply=args.apply, comment=args.comment
+            )
+            for r in results:
+                print(json.dumps(r.to_content(), default=str))
+            print(f"# triaged {len(results)} issue(s); apply={args.apply}")
+        return
+
+    if args.command == "slack-report":
+        from dreaming_memory.integrations.slack import SlackClient
+
+        metrics: dict = {}
+        if args.metrics_json:
+            with open(args.metrics_json, encoding="utf-8") as fh:
+                metrics = json.load(fh)
+        sent = SlackClient().report_eval_result(metrics, run_id=args.run_id)
+        if sent:
+            print(json.dumps({"slack": "sent", "run_id": args.run_id}))
+        else:
+            print(json.dumps({"slack": "skipped", "reason": "no SLACK_WEBHOOK_URL configured"}))
+        return
+
+    if args.command == "export":
+        # Initialize the store/memory BEFORE use; do not rely on the shared
+        # `memory = AgentMemory()` defined later in this function.
+        with AgentMemory() as memory:
+            records = memory.recall(
+                session_id=args.session_id,
+                agent_id=args.agent,
+                limit=100,
+            )
+            markdown = render_export_markdown(args.session_id, records)
+            if args.output:
+                with open(args.output, "w", encoding="utf-8") as fh:
+                    fh.write(markdown)
+                print(json.dumps({
+                    "export": "written", "path": args.output, "records": len(records)
+                }))
+            else:
+                print(markdown)
+        return
+
+    with AgentMemory() as memory:
+        if args.command == "init":
+            memory.ensure_schema()
+            print("Schema applied.")
+            return
+
+        if args.command == "remember":
+            ctx = SessionContext(
+                session_id=args.session_id,
+                session_type=SessionType(args.session_type),
+                agent_id=args.agent,
+            )
+            record = memory.remember(
+                ctx,
+                MemoryType(args.memory_type),
+                json.loads(args.content),
+                source=MemorySource(args.source),
+            )
+            _print_records([record])
+            return
+
+        if args.command == "recall":
+            records = memory.recall(
+                agent_id=args.agent,
+                session_id=args.session_id,
+                session_type=SessionType(args.session_type) if args.session_type else None,
+                memory_type=MemoryType(args.memory_type) if args.memory_type else None,
+                source=MemorySource(args.source) if args.source else None,
+                limit=args.limit,
+            )
+            _print_records(records)
+            return
+
+        if args.command == "linear-ingest":
+            ctx = SessionContext(
+                session_id=args.session_id,
+                session_type=SessionType(args.session_type),
+            )
+            record = memory.linear.ingest_issue(args.issue_id, ctx)
+            _print_records([record])
+            return
+
+        if args.command == "notion-ingest":
+            ctx = SessionContext(
+                session_id=args.session_id,
+                session_type=SessionType(args.session_type),
+            )
+            record = memory.notion.ingest_page(args.page_id, ctx)
+            _print_records([record])
+            return
+
+    parser.print_help()
+    sys.exit(2)
+
+
+if __name__ == "__main__":
+    main()

dreaming_memory/config.py

@@ -0,0 +1,130 @@
+"""Central config + secrets loader for the agent memory fleet.
+
+Resolution order (first match wins):
+1. Process environment (os.environ)
+2. Fleet env file (~/.openclaude/.env — `export KEY="val"` lines, never committed)
+3. Per-host fallback (~/.config/agent-memory/.env)
+
+Only read at runtime; secrets are never written to the repo.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+_EXPORT_RE = re.compile(r'^\s*(?:export\s+)?([A-Z0-9_]+)\s*=\s*(.*)\s*$')
+
+_DEFAULT_SECRET_FILES = (
+    Path(os.environ.get("FLEET_ENV_FILE", "")) if os.environ.get("FLEET_ENV_FILE") else None,
+    Path.home() / ".openclaude" / ".env",
+    Path.home() / ".config" / "agent-memory" / ".env",
+)
+
+
+def _parse_env_file(path: Path | None) -> dict[str, str]:
+    if not path or not path.exists():
+        return {}
+    out: dict[str, str] = {}
+    for line in path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        m = _EXPORT_RE.match(line)
+        if not m:
+            continue
+        key, val = m.group(1), m.group(2)
+        out[key] = val.strip().strip('"').strip("'")
+    return out
+
+
+def load_fleet_secrets(extra_files: tuple[Path, ...] = ()) -> dict[str, str]:
+    """Load fleet env files into os.environ without overwriting existing vars."""
+    merged: dict[str, str] = {}
+    for path in (*_DEFAULT_SECRET_FILES, *extra_files):
+        merged.update(_parse_env_file(path))
+    for key, val in merged.items():
+        os.environ.setdefault(key, val)
+    return merged
+
+
+def get_secret(key: str, default: str | None = None) -> str | None:
+    if key not in os.environ:
+        load_fleet_secrets()
+    return os.environ.get(key, default)
+
+
+@dataclass
+class FleetConfig:
+    """Resolved secrets/config for all integrations across the fleet."""
+
+    database_url: str | None = None
+    linear_api_key: str | None = None
+    linear_team_id: str | None = None
+    notion_api_key: str | None = None
+    cloudflare_api_token: str | None = None
+    cloudflare_account_id: str | None = None
+    sentry_dsn: str | None = None
+    sentry_environment: str = "development"
+    upstash_redis_url: str | None = None
+    upstash_redis_token: str | None = None
+    lance_db_uri: str | None = None
+    r2_bucket: str | None = None
+    r2_access_key_id: str | None = None
+    r2_secret_access_key: str | None = None
+
+    @classmethod
+    def load(cls) -> FleetConfig:
+        load_fleet_secrets()
+        return cls(
+            database_url=(
+                os.environ.get("AGENT_MEMORY_DATABASE_URL")
+                or os.environ.get("DATABASE_URL")
+            ),
+            linear_api_key=os.environ.get("LINEAR_API_KEY"),
+            linear_team_id=os.environ.get("LINEAR_TEAM_ID"),
+            notion_api_key=os.environ.get("NOTION_API_KEY") or os.environ.get("NOTION_TOKEN"),
+            cloudflare_api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),
+            cloudflare_account_id=os.environ.get("CLOUDFLARE_ACCOUNT_ID"),
+            sentry_dsn=os.environ.get("SENTRY_DSN"),
+            sentry_environment=os.environ.get("SENTRY_ENVIRONMENT", "development"),
+            upstash_redis_url=os.environ.get("UPSTASH_REDIS_REST_URL"),
+            upstash_redis_token=os.environ.get("UPSTASH_REDIS_REST_TOKEN"),
+            lance_db_uri=os.environ.get("LANCE_DB_URI"),
+            r2_bucket=os.environ.get("R2_BUCKET")
+            or os.environ.get("AGENT_MEMORY_R2_BUCKET")
+            or "agent-memory",
+            r2_access_key_id=os.environ.get("R2_ACCESS_KEY_ID"),
+            r2_secret_access_key=os.environ.get("R2_SECRET_ACCESS_KEY"),
+        )
+
+    def status(self) -> dict[str, bool]:
+        """Boolean presence map — safe to log (no secret values)."""
+        return {
+            "database_url": bool(self.database_url),
+            "linear": bool(self.linear_api_key),
+            "notion": bool(self.notion_api_key),
+            "cloudflare": bool(self.cloudflare_api_token and self.cloudflare_account_id),
+            "sentry": bool(self.sentry_dsn),
+            "upstash": bool(self.upstash_redis_url and self.upstash_redis_token),
+        }
+
+    def redacted(self) -> dict[str, str]:
+        """Masked summary for logging."""
+
+        def mask(v: str | None) -> str:
+            if not v:
+                return "(unset)"
+            return v[:4] + "…" + v[-2:] if len(v) > 8 else "set"
+
+        return {
+            "database_url": re.sub(r":[^:@/]+@", ":***@", self.database_url or "(unset)"),
+            "linear_api_key": mask(self.linear_api_key),
+            "notion_api_key": mask(self.notion_api_key),
+            "cloudflare_api_token": mask(self.cloudflare_api_token),
+            "cloudflare_account_id": mask(self.cloudflare_account_id),
+            "sentry_dsn": "set" if self.sentry_dsn else "(unset)",
+            "lance_db_uri": self.lance_db_uri or "(unset)",
+        }