episodicdb 0.1.0__py3-none-any.whl

episodicdb/__init__.py

@@ -0,0 +1,8 @@
+from episodicdb.db import EpisodicDB
+
+
+class EpisodicDBError(Exception):
+    """Base exception for EpisodicDB."""
+
+
+__all__ = ["EpisodicDB", "EpisodicDBError"]

episodicdb/analytics.py

@@ -0,0 +1,220 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from episodicdb.schema import EMBEDDING_DIM
+
+
+class AnalyticsMixin:
+    """Mixin providing analytics methods. Requires self._conn and self.agent_id."""
+
+    def top_failing_tools(
+        self,
+        days: int = 7,
+        limit: int = 5,
+    ) -> list[dict]:
+        rows = self._conn.execute(
+            """
+            SELECT tc.tool_name, COUNT(*) AS failures
+            FROM tool_calls tc
+            JOIN episodes e ON e.id = tc.episode_id
+            WHERE tc.outcome = 'failure'
+              AND e.agent_id = $1
+              AND tc.called_at >= NOW() - INTERVAL (CAST($2 AS VARCHAR) || ' days')
+            GROUP BY tc.tool_name
+            ORDER BY failures DESC
+            LIMIT $3
+            """,
+            [self.agent_id, days, limit],
+        ).fetchall()
+        return [{"tool_name": r[0], "failures": r[1]} for r in rows]
+
+    def never_succeeded_tools(self) -> list[str]:
+        rows = self._conn.execute(
+            """
+            SELECT DISTINCT tc.tool_name
+            FROM tool_calls tc
+            JOIN episodes e ON e.id = tc.episode_id
+            WHERE e.agent_id = $1
+              AND tc.tool_name NOT IN (
+                SELECT DISTINCT tc2.tool_name
+                FROM tool_calls tc2
+                JOIN episodes e2 ON e2.id = tc2.episode_id
+                WHERE e2.agent_id = $1
+                  AND tc2.outcome = 'success'
+            )
+            ORDER BY tc.tool_name
+            """,
+            [self.agent_id],
+        ).fetchall()
+        return [r[0] for r in rows]
+
+    def hourly_failure_rate(
+        self,
+        days: int = 7,
+    ) -> list[dict]:
+        rows = self._conn.execute(
+            """
+            SELECT
+                hour(tc.called_at) AS hour,
+                COUNT(*) AS total,
+                SUM(CASE WHEN tc.outcome = 'failure' THEN 1 ELSE 0 END) AS failures
+            FROM tool_calls tc
+            JOIN episodes e ON e.id = tc.episode_id
+            WHERE e.agent_id = $1
+              AND tc.called_at >= NOW() - INTERVAL (CAST($2 AS VARCHAR) || ' days')
+            GROUP BY hour(tc.called_at)
+            ORDER BY hour(tc.called_at)
+            """,
+            [self.agent_id, days],
+        ).fetchall()
+        return [{"hour": r[0], "total": r[1], "failures": r[2]} for r in rows]
+
+    def compare_periods(
+        self,
+        metric: Literal["failure_rate", "episode_count", "tool_calls"],
+        days: int = 7,
+    ) -> dict:
+        if metric == "failure_rate":
+            row = self._conn.execute(
+                """
+                SELECT
+                    AVG(CASE WHEN tc.called_at >= NOW() - INTERVAL (CAST($2 AS VARCHAR) || ' days')
+                             THEN CASE WHEN tc.outcome = 'failure' THEN 1.0 ELSE 0.0 END
+                             ELSE NULL END) AS period_a,
+                    AVG(CASE WHEN tc.called_at >= NOW() - INTERVAL (CAST($3 AS VARCHAR) || ' days')
+                              AND tc.called_at <  NOW() - INTERVAL (CAST($2 AS VARCHAR) || ' days')
+                             THEN CASE WHEN tc.outcome = 'failure' THEN 1.0 ELSE 0.0 END
+                             ELSE NULL END) AS period_b
+                FROM tool_calls tc
+                JOIN episodes e ON e.id = tc.episode_id
+                WHERE e.agent_id = $1
+                  AND tc.called_at >= NOW() - INTERVAL (CAST($3 AS VARCHAR) || ' days')
+                """,
+                [self.agent_id, days, days * 2],
+            ).fetchone()
+            a = row[0] or 0.0
+            b = row[1] or 0.0
+        elif metric == "episode_count":
+            row = self._conn.execute(
+                """
+                SELECT
+                    COUNT(*) FILTER (WHERE started_at >= NOW() - INTERVAL (CAST($2 AS VARCHAR) || ' days')) AS period_a,
+                    COUNT(*) FILTER (WHERE started_at >= NOW() - INTERVAL (CAST($3 AS VARCHAR) || ' days')
+                                       AND started_at <  NOW() - INTERVAL (CAST($2 AS VARCHAR) || ' days')) AS period_b
+                FROM episodes
+                WHERE agent_id = $1
+                  AND started_at >= NOW() - INTERVAL (CAST($3 AS VARCHAR) || ' days')
+                """,
+                [self.agent_id, days, days * 2],
+            ).fetchone()
+            a = float(row[0] or 0)
+            b = float(row[1] or 0)
+        else:  # tool_calls
+            row = self._conn.execute(
+                """
+                SELECT
+                    COUNT(*) FILTER (WHERE tc.called_at >= NOW() - INTERVAL (CAST($2 AS VARCHAR) || ' days')) AS period_a,
+                    COUNT(*) FILTER (WHERE tc.called_at >= NOW() - INTERVAL (CAST($3 AS VARCHAR) || ' days')
+                                       AND tc.called_at <  NOW() - INTERVAL (CAST($2 AS VARCHAR) || ' days')) AS period_b
+                FROM tool_calls tc
+                JOIN episodes e ON e.id = tc.episode_id
+                WHERE e.agent_id = $1
+                  AND tc.called_at >= NOW() - INTERVAL (CAST($3 AS VARCHAR) || ' days')
+                """,
+                [self.agent_id, days, days * 2],
+            ).fetchone()
+            a = float(row[0] or 0)
+            b = float(row[1] or 0)
+
+        return {"period_a": round(a, 4), "period_b": round(b, 4), "delta": round(a - b, 4)}
+
+    def before_failure_sequence(
+        self,
+        tool_name: str,
+        lookback: int = 3,
+    ) -> list[dict]:
+        """Aggregate tool calls immediately before tool_name failures."""
+        lag_cols = ", ".join(
+            f"LAG(tc.tool_name, {i}) OVER (ORDER BY tc.called_at) AS prev_{i}"
+            for i in range(1, lookback + 1)
+        )
+        prev_selects = " UNION ALL ".join(
+            f"SELECT prev_{i} AS prev_tool FROM failures WHERE prev_{i} IS NOT NULL"
+            for i in range(1, lookback + 1)
+        )
+        rows = self._conn.execute(
+            f"""
+            WITH sequenced AS (
+                SELECT
+                    tc.tool_name,
+                    tc.outcome,
+                    {lag_cols}
+                FROM tool_calls tc
+                JOIN episodes e ON e.id = tc.episode_id
+                WHERE e.agent_id = $1
+            ),
+            failures AS (
+                SELECT * FROM sequenced
+                WHERE tool_name = $2 AND outcome = 'failure'
+            )
+            SELECT prev_tool, COUNT(*) AS cnt FROM (
+                {prev_selects}
+            )
+            GROUP BY prev_tool
+            ORDER BY cnt DESC
+            """,
+            [self.agent_id, tool_name],
+        ).fetchall()
+        return [{"prev_tool": r[0], "count": r[1]} for r in rows]
+
+    def similar_episodes(
+        self,
+        embedding: list[float],
+        status: str | None = None,
+        limit: int = 5,
+    ) -> list[dict]:
+        """SQL predicate + vector similarity in a single execution plan."""
+        if len(embedding) != EMBEDDING_DIM:
+            raise ValueError(f"Expected {EMBEDDING_DIM} dimensions, got {len(embedding)}")
+
+        params: list = [embedding, self.agent_id]
+        status_clause = ""
+        if status is not None:
+            status_clause = "AND status = $3"
+            params.append(status)
+        params.append(limit)
+        limit_param = f"${len(params)}"
+
+        rows = self._conn.execute(
+            f"""
+            SELECT
+                id::TEXT,
+                agent_id,
+                status,
+                task_type,
+                started_at,
+                ended_at,
+                array_cosine_distance(context_embedding, $1::FLOAT[{EMBEDDING_DIM}]) AS distance
+            FROM episodes
+            WHERE context_embedding IS NOT NULL
+              AND agent_id = $2
+              {status_clause}
+            ORDER BY distance ASC
+            LIMIT {limit_param}
+            """,
+            params,
+        ).fetchall()
+
+        return [
+            {
+                "id": r[0],
+                "agent_id": r[1],
+                "status": r[2],
+                "task_type": r[3],
+                "started_at": r[4],
+                "ended_at": r[5],
+                "distance": r[6],
+            }
+            for r in rows
+        ]

episodicdb/db.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+import duckdb
+
+logger = logging.getLogger(__name__)
+
+from episodicdb.analytics import AnalyticsMixin
+from episodicdb.temporal import TemporalMixin
+from episodicdb.writer import WriterMixin
+from episodicdb.schema import (
+    CALLED_AT_INDEX_DDL,
+    DECISIONS_DDL,
+    EPISODES_DDL,
+    FACTS_DDL,
+    FACTS_KEY_IDX_DDL,
+    HNSW_INDEX_DDL,
+    STARTED_AT_INDEX_DDL,
+    TOOL_CALLS_DDL,
+)
+
+_DEFAULT_DIR = Path.home() / ".episodicdb"
+
+
+class EpisodicDB(WriterMixin, AnalyticsMixin, TemporalMixin):
+    def __init__(self, agent_id: str, path: str | None = None) -> None:
+        self.agent_id = agent_id
+
+        if path is None:
+            _DEFAULT_DIR.mkdir(parents=True, exist_ok=True)
+            resolved = str(_DEFAULT_DIR / f"{agent_id}.db")
+        else:
+            resolved = path
+
+        try:
+            self._conn = duckdb.connect(resolved)
+        except Exception as exc:
+            from episodicdb import EpisodicDBError
+            raise EpisodicDBError(f"Cannot open database: {resolved}") from exc
+
+        self._load_vss()
+        self._init_schema()
+
+    def _load_vss(self) -> None:
+        try:
+            self._conn.execute("LOAD vss")
+        except Exception:
+            try:
+                self._conn.execute("INSTALL vss; LOAD vss")
+            except Exception as exc:
+                from episodicdb import EpisodicDBError
+                raise EpisodicDBError("VSS extension unavailable") from exc
+
+    def _init_schema(self) -> None:
+        self._conn.execute(EPISODES_DDL)
+        self._conn.execute(TOOL_CALLS_DDL)
+        self._conn.execute(DECISIONS_DDL)
+        self._conn.execute(FACTS_DDL)
+        try:
+            self._conn.execute("SET hnsw_enable_experimental_persistence = true")
+        except Exception:
+            logger.warning(
+                "hnsw_enable_experimental_persistence not supported; "
+                "HNSW index will not persist across restarts"
+            )
+        self._conn.execute(HNSW_INDEX_DDL)
+        self._conn.execute(CALLED_AT_INDEX_DDL)
+        self._conn.execute(STARTED_AT_INDEX_DDL)
+        self._conn.execute(FACTS_KEY_IDX_DDL)
+
+    def close(self) -> None:
+        self._conn.close()
+
+    def __enter__(self) -> "EpisodicDB":
+        return self
+
+    def __exit__(self, *_) -> None:
+        self.close()

episodicdb/mcp/__main__.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+import argparse
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="EpisodicDB MCP Server")
+    parser.add_argument("--agent-id", required=True, help="Default agent ID")
+    parser.add_argument("--db", default=None, help="DuckDB file path (default: ~/.episodicdb/{agent_id}.db)")
+    args = parser.parse_args()
+
+    from episodicdb.mcp.server import serve
+    serve(agent_id=args.agent_id, db_path=args.db)
+
+
+if __name__ == "__main__":
+    main()

episodicdb/mcp/server.py

@@ -0,0 +1,235 @@
+from __future__ import annotations
+
+import json
+from contextlib import contextmanager
+from datetime import datetime
+
+from mcp.server.fastmcp import FastMCP
+
+from episodicdb.db import EpisodicDB
+
+_db: EpisodicDB | None = None
+_default_agent_id: str = ""
+
+
+def _get_db() -> EpisodicDB:
+    assert _db is not None, "Server not initialized"
+    return _db
+
+
+@contextmanager
+def _agent_scope(agent_id: str | None):
+    """Temporarily override the DB's agent_id, restoring it on exit."""
+    db = _get_db()
+    original = db.agent_id
+    db.agent_id = agent_id if agent_id is not None else _default_agent_id
+    try:
+        yield db
+    finally:
+        db.agent_id = original
+
+
+def _serialize_timestamps(rows: list[dict], keys: list[str]) -> list[dict]:
+    """Convert datetime fields to ISO strings for JSON serialization."""
+    for r in rows:
+        for k in keys:
+            if r.get(k):
+                r[k] = r[k].isoformat()
+    return rows
+
+
+mcp_server = FastMCP("episodicdb")
+
+
+# --- Writer tools ---
+
+
+@mcp_server.tool()
+def record_episode(
+    status: str,
+    task_type: str | None = None,
+    context: dict | None = None,
+    embedding: list[float] | None = None,
+    tags: list[str] | None = None,
+    started_at: str | None = None,
+    ended_at: str | None = None,
+    agent_id: str | None = None,
+) -> str:
+    """Record an episode (task/session) for an agent."""
+    with _agent_scope(agent_id) as db:
+        return db.record_episode(
+            status=status,
+            task_type=task_type,
+            context=context,
+            embedding=embedding,
+            tags=tags,
+            started_at=datetime.fromisoformat(started_at) if started_at else None,
+            ended_at=datetime.fromisoformat(ended_at) if ended_at else None,
+        )
+
+
+@mcp_server.tool()
+def record_tool_call(
+    episode_id: str,
+    tool_name: str,
+    outcome: str,
+    parameters: dict | None = None,
+    result: dict | None = None,
+    duration_ms: int | None = None,
+    error_message: str | None = None,
+    called_at_override: str | None = None,
+    agent_id: str | None = None,
+) -> str:
+    """Record a tool call within an episode."""
+    with _agent_scope(agent_id) as db:
+        return db.record_tool_call(
+            episode_id=episode_id,
+            tool_name=tool_name,
+            outcome=outcome,
+            parameters=parameters,
+            result=result,
+            duration_ms=duration_ms,
+            error_message=error_message,
+            called_at_override=datetime.fromisoformat(called_at_override) if called_at_override else None,
+        )
+
+
+@mcp_server.tool()
+def record_decision(
+    episode_id: str,
+    rationale: str,
+    decision_type: str | None = None,
+    alternatives: list | None = None,
+    outcome: str | None = None,
+    agent_id: str | None = None,
+) -> str:
+    """Record a decision made during an episode."""
+    with _agent_scope(agent_id) as db:
+        return db.record_decision(
+            episode_id=episode_id,
+            rationale=rationale,
+            decision_type=decision_type,
+            alternatives=alternatives,
+            outcome=outcome,
+        )
+
+
+@mcp_server.tool()
+def record_fact(
+    key: str,
+    value: str,
+    episode_id: str | None = None,
+    valid_from: str | None = None,
+    agent_id: str | None = None,
+) -> str:
+    """Record a fact with automatic supersession of previous values."""
+    with _agent_scope(agent_id) as db:
+        return db.record_fact(
+            key=key,
+            value=value,
+            episode_id=episode_id,
+            valid_from=datetime.fromisoformat(valid_from) if valid_from else None,
+        )
+
+
+# --- Analytics tools ---
+
+
+@mcp_server.tool()
+def top_failing_tools(
+    days: int = 7,
+    limit: int = 5,
+    agent_id: str | None = None,
+) -> str:
+    """Get tools with the most failures, ranked by failure count."""
+    with _agent_scope(agent_id) as db:
+        return json.dumps(db.top_failing_tools(days=days, limit=limit))
+
+
+@mcp_server.tool()
+def never_succeeded_tools(
+    agent_id: str | None = None,
+) -> str:
+    """List tools that have never had a successful outcome."""
+    with _agent_scope(agent_id) as db:
+        return json.dumps(db.never_succeeded_tools())
+
+
+@mcp_server.tool()
+def hourly_failure_rate(
+    days: int = 7,
+    agent_id: str | None = None,
+) -> str:
+    """Get failure counts grouped by hour of day."""
+    with _agent_scope(agent_id) as db:
+        return json.dumps(db.hourly_failure_rate(days=days))
+
+
+@mcp_server.tool()
+def compare_periods(
+    metric: str,
+    days: int = 7,
+    agent_id: str | None = None,
+) -> str:
+    """Compare a metric between two consecutive time periods."""
+    with _agent_scope(agent_id) as db:
+        return json.dumps(db.compare_periods(metric=metric, days=days))
+
+
+@mcp_server.tool()
+def before_failure_sequence(
+    tool_name: str,
+    lookback: int = 3,
+    agent_id: str | None = None,
+) -> str:
+    """Find which tools commonly precede failures of a given tool."""
+    with _agent_scope(agent_id) as db:
+        return json.dumps(db.before_failure_sequence(tool_name=tool_name, lookback=lookback))
+
+
+@mcp_server.tool()
+def similar_episodes(
+    embedding: list[float],
+    status: str | None = None,
+    limit: int = 5,
+    agent_id: str | None = None,
+) -> str:
+    """Find episodes most similar to a given embedding vector."""
+    with _agent_scope(agent_id) as db:
+        results = db.similar_episodes(embedding=embedding, status=status, limit=limit)
+        return json.dumps(_serialize_timestamps(results, ["started_at", "ended_at"]))
+
+
+# --- Temporal tools ---
+
+
+@mcp_server.tool()
+def facts_as_of(
+    as_of: str,
+    agent_id: str | None = None,
+) -> str:
+    """Return all facts that were valid at a specific point in time."""
+    with _agent_scope(agent_id) as db:
+        results = db.facts_as_of(as_of=datetime.fromisoformat(as_of))
+        return json.dumps(_serialize_timestamps(results, ["valid_from", "valid_until"]))
+
+
+@mcp_server.tool()
+def fact_history(
+    key: str,
+    agent_id: str | None = None,
+) -> str:
+    """Return the full change history of a fact key."""
+    with _agent_scope(agent_id) as db:
+        results = db.fact_history(key=key)
+        return json.dumps(_serialize_timestamps(results, ["valid_from", "valid_until"]))
+
+
+def serve(agent_id: str, db_path: str | None = None) -> None:
+    global _db, _default_agent_id
+    _default_agent_id = agent_id
+    _db = EpisodicDB(agent_id=agent_id, path=db_path)
+    try:
+        mcp_server.run(transport="stdio")
+    finally:
+        _db.close()

episodicdb/schema/__init__.py

@@ -0,0 +1,75 @@
+EMBEDDING_DIM = 1536
+
+EPISODES_DDL = """
+CREATE TABLE IF NOT EXISTS episodes (
+    id                UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    agent_id          TEXT NOT NULL,
+    started_at        TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    ended_at          TIMESTAMPTZ,
+    status            TEXT NOT NULL
+                        CHECK (status IN ('success', 'failure', 'partial', 'aborted')),
+    task_type         TEXT,
+    context           JSON,
+    context_embedding FLOAT[1536],
+    tags              TEXT[]
+);
+"""
+
+TOOL_CALLS_DDL = """
+CREATE TABLE IF NOT EXISTS tool_calls (
+    id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    episode_id    UUID NOT NULL REFERENCES episodes(id),
+    called_at     TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    tool_name     TEXT NOT NULL,
+    parameters    JSON,
+    result        JSON,
+    outcome       TEXT NOT NULL
+                    CHECK (outcome IN ('success', 'failure', 'timeout', 'error')),
+    duration_ms   INTEGER,
+    error_message TEXT
+);
+"""
+
+DECISIONS_DDL = """
+CREATE TABLE IF NOT EXISTS decisions (
+    id             UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    episode_id     UUID NOT NULL REFERENCES episodes(id),
+    decided_at     TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    decision_type  TEXT,
+    rationale      TEXT,
+    alternatives   JSON,
+    outcome        TEXT
+);
+"""
+
+FACTS_DDL = """
+CREATE TABLE IF NOT EXISTS facts (
+    id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    agent_id    TEXT NOT NULL,
+    key         TEXT NOT NULL,
+    value       TEXT NOT NULL,
+    valid_from  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    valid_until TIMESTAMPTZ,
+    episode_id  UUID REFERENCES episodes(id)
+);
+"""
+
+FACTS_KEY_IDX_DDL = """
+CREATE INDEX IF NOT EXISTS facts_key_idx
+ON facts (agent_id, key, valid_from);
+"""
+
+HNSW_INDEX_DDL = """
+CREATE INDEX IF NOT EXISTS episodes_embedding_idx
+ON episodes USING HNSW (context_embedding);
+"""
+
+CALLED_AT_INDEX_DDL = """
+CREATE INDEX IF NOT EXISTS tool_calls_called_at_idx
+ON tool_calls (called_at);
+"""
+
+STARTED_AT_INDEX_DDL = """
+CREATE INDEX IF NOT EXISTS episodes_started_at_idx
+ON episodes (started_at);
+"""

episodicdb/temporal.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from datetime import datetime
+
+
+class TemporalMixin:
+    """Mixin providing temporal fact queries. Requires self._conn and self.agent_id."""
+
+    def facts_as_of(
+        self,
+        as_of: datetime,
+    ) -> list[dict]:
+        """Return all facts that were valid at a specific point in time.
+
+        This is the temporal point-in-time query that DuckDB has no native
+        syntax for (no AS OF, no temporal tables). Every caller would need
+        to manually write the valid_from/valid_until predicate.
+        """
+        rows = self._conn.execute(
+            """
+            SELECT key, value, valid_from, valid_until, episode_id::TEXT
+            FROM facts
+            WHERE agent_id = $1
+              AND valid_from <= $2
+              AND (valid_until IS NULL OR valid_until > $2)
+            ORDER BY key
+            """,
+            [self.agent_id, as_of],
+        ).fetchall()
+        return [
+            {
+                "key": r[0],
+                "value": r[1],
+                "valid_from": r[2],
+                "valid_until": r[3],
+                "episode_id": r[4],
+            }
+            for r in rows
+        ]
+
+    def fact_history(
+        self,
+        key: str,
+    ) -> list[dict]:
+        """Return the full change history of a fact key, ordered chronologically."""
+        rows = self._conn.execute(
+            """
+            SELECT value, valid_from, valid_until, episode_id::TEXT
+            FROM facts
+            WHERE agent_id = $1 AND key = $2
+            ORDER BY valid_from ASC
+            """,
+            [self.agent_id, key],
+        ).fetchall()
+        return [
+            {
+                "value": r[0],
+                "valid_from": r[1],
+                "valid_until": r[2],
+                "episode_id": r[3],
+            }
+            for r in rows
+        ]

episodicdb/writer.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from typing import Literal
+
+from episodicdb.schema import EMBEDDING_DIM
+
+
+class WriterMixin:
+    """Mixin providing write methods. Requires self._conn and self.agent_id."""
+
+    def record_episode(
+        self,
+        status: Literal["success", "failure", "partial", "aborted"],
+        task_type: str | None = None,
+        context: dict | None = None,
+        embedding: list[float] | None = None,
+        tags: list[str] | None = None,
+        started_at: datetime | None = None,
+        ended_at: datetime | None = None,
+    ) -> str:
+        if embedding is not None and len(embedding) != EMBEDDING_DIM:
+            raise ValueError(
+                f"Expected {EMBEDDING_DIM} dimensions, got {len(embedding)}"
+            )
+
+        context_json = json.dumps(context) if context is not None else None
+
+        row = self._conn.execute(
+            """
+            INSERT INTO episodes
+                (agent_id, status, task_type, context, context_embedding, tags,
+                 started_at, ended_at)
+            VALUES ($1, $2, $3, $4, $5, $6,
+                    COALESCE($7, NOW()), $8)
+            RETURNING id::TEXT
+            """,
+            [
+                self.agent_id,
+                status,
+                task_type,
+                context_json,
+                embedding,
+                tags,
+                started_at,
+                ended_at,
+            ],
+        ).fetchone()
+        return row[0]
+
+    def record_tool_call(
+        self,
+        episode_id: str,
+        tool_name: str,
+        outcome: Literal["success", "failure", "timeout", "error"],
+        parameters: dict | None = None,
+        result: dict | None = None,
+        duration_ms: int | None = None,
+        error_message: str | None = None,
+        called_at_override: datetime | None = None,
+    ) -> str:
+        params_json = json.dumps(parameters) if parameters is not None else None
+        result_json = json.dumps(result) if result is not None else None
+
+        row = self._conn.execute(
+            """
+            INSERT INTO tool_calls
+                (episode_id, tool_name, outcome, parameters, result,
+                 duration_ms, error_message, called_at)
+            VALUES ($1, $2, $3, $4, $5, $6, $7,
+                    COALESCE($8, NOW()))
+            RETURNING id::TEXT
+            """,
+            [
+                episode_id,
+                tool_name,
+                outcome,
+                params_json,
+                result_json,
+                duration_ms,
+                error_message,
+                called_at_override,
+            ],
+        ).fetchone()
+        return row[0]
+
+    def record_decision(
+        self,
+        episode_id: str,
+        rationale: str,
+        decision_type: str | None = None,
+        alternatives: list | None = None,
+        outcome: str | None = None,
+    ) -> str:
+        alts_json = json.dumps(alternatives) if alternatives is not None else None
+
+        row = self._conn.execute(
+            """
+            INSERT INTO decisions
+                (episode_id, rationale, decision_type, alternatives, outcome)
+            VALUES ($1, $2, $3, $4, $5)
+            RETURNING id::TEXT
+            """,
+            [episode_id, rationale, decision_type, alts_json, outcome],
+        ).fetchone()
+        return row[0]
+
+    def record_fact(
+        self,
+        key: str,
+        value: str,
+        episode_id: str | None = None,
+        valid_from: datetime | None = None,
+    ) -> str:
+        """Record a fact with automatic supersession.
+
+        If a fact with the same key already exists (for this agent) and has no
+        valid_until, its validity window is closed at the new fact's valid_from.
+        This is the temporal supersession pattern that DuckDB cannot enforce
+        natively (no triggers, no temporal constraints).
+        """
+        self._conn.execute("BEGIN TRANSACTION")
+        try:
+            # Close the currently-active fact for this key (auto-supersession)
+            self._conn.execute(
+                """
+                UPDATE facts
+                SET valid_until = COALESCE($3, NOW())
+                WHERE agent_id = $1
+                  AND key = $2
+                  AND valid_until IS NULL
+                """,
+                [self.agent_id, key, valid_from],
+            )
+
+            row = self._conn.execute(
+                """
+                INSERT INTO facts
+                    (agent_id, key, value, valid_from, episode_id)
+                VALUES ($1, $2, $3, COALESCE($4, NOW()), $5)
+                RETURNING id::TEXT
+                """,
+                [self.agent_id, key, value, valid_from, episode_id],
+            ).fetchone()
+            self._conn.execute("COMMIT")
+        except Exception:
+            self._conn.execute("ROLLBACK")
+            raise
+        return row[0]

episodicdb-0.1.0.dist-info/METADATA

@@ -0,0 +1,260 @@
+Metadata-Version: 2.4
+Name: episodicdb
+Version: 0.1.0
+Summary: OLAP-based memory engine for AI agents
+Project-URL: Homepage, https://github.com/KsPsD/EpisodicDB
+Project-URL: Repository, https://github.com/KsPsD/EpisodicDB
+Project-URL: Issues, https://github.com/KsPsD/EpisodicDB/issues
+Author: KsPsD
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,duckdb,mcp,memory,olap,vector
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: duckdb>=1.2.0
+Requires-Dist: mcp[cli]>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# EpisodicDB
+
+**An OLAP-based memory engine for AI agents.**
+
+Existing agent memory systems (Mem0, Zep, Letta) are designed as *search systems*. EpisodicDB treats agent memory as an *analytics problem* — aggregation, time-series patterns, causal tracing, temporal facts, and vector similarity all in a single query engine.
+
+```sql
+-- "Which tools failed most this week?"
+SELECT tool_name, COUNT(*) AS failures
+FROM tool_calls
+WHERE outcome = 'failure'
+  AND called_at >= NOW() - INTERVAL '7 days'
+GROUP BY tool_name
+ORDER BY failures DESC;
+
+-- "Find past episodes similar to this context that succeeded"
+SELECT *, array_cosine_distance(context_embedding, ?) AS dist
+FROM episodes
+WHERE status = 'success'
+ORDER BY dist ASC
+LIMIT 5;
+```
+
+## The Problem
+
+| Query type | Example | Vector search? |
+|------------|---------|----------------|
+| Similarity | "Seen a similar error before?" | Yes |
+| Aggregation | "How many tool failures this week?" | No |
+| Time-series | "Do failures spike in the afternoon?" | No |
+| Causal trace | "What tool ran right before failures?" | No |
+| Comparison | "Worse than last week?" | No |
+| Absence | "Tools that never succeeded?" | No |
+| Temporal | "What was the user's timezone last Tuesday?" | No |
+
+EpisodicDB answers all of them. Vector similarity is just another SQL operator.
+
+## Architecture
+
+```
+EpisodicDB
+├── WriterMixin      record_episode / record_tool_call / record_decision / record_fact
+├── AnalyticsMixin   6 analytics methods + vector similarity
+└── TemporalMixin    facts_as_of / fact_history
+
+Engine: DuckDB (OLAP) + VSS extension (HNSW vector index)
+Schema: episodes + tool_calls + decisions + facts
+```
+
+## Install
+
+```bash
+pip install episodicdb
+```
+
+## Quick Start
+
+### Python SDK
+
+```python
+from episodicdb import EpisodicDB
+
+with EpisodicDB(agent_id="my-agent") as db:
+    # Record what happened
+    ep_id = db.record_episode(
+        status="failure",
+        task_type="file_edit",
+        context={"file": "auth.py", "error": "permission denied"},
+    )
+    db.record_tool_call(ep_id, "Edit", "failure",
+                        duration_ms=120, error_message="permission denied")
+    db.record_tool_call(ep_id, "Bash", "success", duration_ms=50)
+
+    # Record temporal facts (auto-supersedes previous values)
+    db.record_fact("user_timezone", "Asia/Seoul", episode_id=ep_id)
+    db.record_fact("user_timezone", "America/New_York")  # closes previous
+
+    # Analyze patterns
+    print(db.top_failing_tools(days=7))
+    # [{"tool_name": "Edit", "failures": 5}, ...]
+
+    print(db.before_failure_sequence("Edit"))
+    # [{"prev_tool": "Bash", "count": 4}, ...]
+
+    print(db.compare_periods("failure_rate", days=7))
+    # {"period_a": 0.32, "period_b": 0.18, "delta": 0.14}
+
+    # Time-travel query
+    from datetime import datetime
+    print(db.facts_as_of(datetime(2025, 3, 15)))
+    # [{"key": "user_timezone", "value": "Asia/Seoul", ...}]
+```
+
+### MCP Server (Claude, OpenAI Agents SDK)
+
+EpisodicDB ships an MCP server with 12 tools over stdio.
+
+```bash
+episodicdb-mcp --agent-id my-agent
+episodicdb-mcp --agent-id my-agent --db ./memory.db
+```
+
+**Claude Desktop** (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "episodicdb": {
+      "command": "episodicdb-mcp",
+      "args": ["--agent-id", "my-agent"]
+    }
+  }
+}
+```
+
+**Claude Code** (`.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "episodicdb": {
+      "command": "episodicdb-mcp",
+      "args": ["--agent-id", "my-agent"]
+    }
+  }
+}
+```
+
+**OpenAI Agents SDK**:
+
+```python
+from agents import Agent
+from agents.mcp import MCPServerStdio
+
+agent = Agent(
+    name="my-agent",
+    instructions="You have access to episodic memory.",
+    mcp_servers=[MCPServerStdio(
+        command="episodicdb-mcp",
+        args=["--agent-id", "my-agent"],
+    )],
+)
+```
+
+## API
+
+### Writer
+
+```python
+db.record_episode(status, task_type=None, context=None,
+                  embedding=None, tags=None,
+                  started_at=None, ended_at=None) -> str  # episode UUID
+
+db.record_tool_call(episode_id, tool_name, outcome,
+                    parameters=None, result=None,
+                    duration_ms=None, error_message=None) -> str
+
+db.record_decision(episode_id, rationale,
+                   decision_type=None, alternatives=None,
+                   outcome=None) -> str
+
+db.record_fact(key, value, episode_id=None,
+               valid_from=None) -> str  # auto-supersedes previous
+```
+
+### Analytics
+
+| Method | Description |
+|--------|-------------|
+| `top_failing_tools(days, limit)` | Most-failed tools in the last N days |
+| `hourly_failure_rate(days)` | Failure count by hour of day |
+| `before_failure_sequence(tool_name, lookback)` | Tools that precede failures |
+| `compare_periods(metric, days)` | Period-over-period comparison |
+| `never_succeeded_tools()` | Tools with zero successful calls |
+| `similar_episodes(embedding, status, limit)` | Vector similarity + SQL filter |
+
+### Temporal Facts
+
+Facts are key-value pairs with automatic temporal validity. Recording a new value for the same key closes the previous one.
+
+```python
+db.record_fact("preferred_model", "gpt-4o")
+# later...
+db.record_fact("preferred_model", "claude-sonnet")  # supersedes gpt-4o
+
+db.facts_as_of(some_datetime)   # point-in-time snapshot
+db.fact_history("preferred_model")  # full change log
+```
+
+### Persistence
+
+```python
+EpisodicDB(agent_id="my-agent")                    # ~/.episodicdb/my-agent.db
+EpisodicDB(agent_id="my-agent", path="./x.db")    # explicit path
+EpisodicDB(agent_id="my-agent", path=":memory:")  # in-memory (testing)
+```
+
+### Embeddings
+
+EpisodicDB does not generate embeddings. Pass them in:
+
+```python
+import openai
+
+response = openai.embeddings.create(
+    model="text-embedding-3-small",
+    input="what the agent was doing"
+)
+embedding = response.data[0].embedding  # 1536 dims
+
+db.record_episode(status="success", embedding=embedding)
+db.similar_episodes(embedding, status="failure", limit=5)
+```
+
+## Development
+
+```bash
+git clone https://github.com/KsPsD/EpisodicDB
+cd EpisodicDB
+pip install -e ".[dev]"
+pytest
+```
+
+## Stack
+
+- [DuckDB](https://duckdb.org/) — embedded OLAP engine
+- [DuckDB VSS](https://duckdb.org/docs/extensions/vss) — HNSW vector index
+- [MCP](https://modelcontextprotocol.io/) — Model Context Protocol server
+- Python 3.11+
+
+## License
+
+MIT

episodicdb-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+episodicdb/__init__.py,sha256=wV1B5rUdxe4yYOCy7alw1hYTkYFwUULYiXZ80W5whXc,160
+episodicdb/analytics.py,sha256=Pfu38f84MFBCso_l1gfQxtVCmQ8mUI4JqI_X0pFYMqc,8152
+episodicdb/db.py,sha256=KjWJzlKRnKgRQK3sRSdX10LHc0KLLJBh3XY2SnRsRME,2370
+episodicdb/temporal.py,sha256=0hTpCDlEuN5vGeGuDTrQcN4ZefZCGE6oNqS3RJmNJ5A,1859
+episodicdb/writer.py,sha256=k2o9EZRD_AWxWT3seiTVXaByRAKfMyu45midJWSjeO4,4898
+episodicdb/mcp/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+episodicdb/mcp/__main__.py,sha256=y5LecI5Xc-pWlyb0Ow52Y8FT3Vs4bNVTIEFTcae-XSc,503
+episodicdb/mcp/server.py,sha256=G-lDOlgxJ9B6B-OuLAJ4fkUi4Etc9mBuVkXje_v9N_E,6524
+episodicdb/schema/__init__.py,sha256=rtWMgekSDKUnqkOaPLxNJU5E6zkYFSl1xFplLueroKc,2141
+episodicdb-0.1.0.dist-info/METADATA,sha256=Crq3moPt2U5fTxqvFUmweR-PgWlvX6kvrt_-OQF1Dkc,7367
+episodicdb-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+episodicdb-0.1.0.dist-info/entry_points.txt,sha256=dQMBwLmSqV9YUFLoNIEV8e4SyXFyWDF_oVMfCWQnYaM,64
+episodicdb-0.1.0.dist-info/licenses/LICENSE,sha256=_9RoRqFzqcEFikLzPZ0ATwV4787xKOGKrLzJTHUhCH4,1062
+episodicdb-0.1.0.dist-info/RECORD,,

episodicdb-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

episodicdb-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+episodicdb-mcp = episodicdb.mcp.__main__:main

episodicdb-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KsPsD
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.