claude-memory-agent 2.2.2 → 2.2.4

package/main.py

@@ -108,6 +108,9 @@ from services.confidence import get_confidence_service
 # CLAUDE.md sync service
 from services.claude_md_sync import get_claude_md_sync
 
+# Cross-session awareness
+from services.session_awareness import get_session_awareness
+
 # Agent registry for dashboard
 from services.agent_registry import (
     AVAILABLE_AGENTS, AVAILABLE_MCPS, AVAILABLE_HOOKS,
@@ -293,6 +296,26 @@ async def lifespan(app: FastAPI):
 
     consolidation_task = asyncio.create_task(consolidation_loop())
 
+    # Start cross-session stale cleanup loop
+    async def session_cleanup_loop():
+        """Background: clean up stale/expired sessions."""
+        interval = app_config.SESSION_CLEANUP_INTERVAL_SECONDS
+        while True:
+            await asyncio.sleep(interval)
+            try:
+                awareness = get_session_awareness(db)
+                result = await awareness.cleanup_stale(
+                    idle_minutes=app_config.SESSION_IDLE_THRESHOLD_MINUTES,
+                    completed_minutes=app_config.SESSION_COMPLETED_THRESHOLD_MINUTES,
+                )
+                total = sum(result.values())
+                if total > 0:
+                    logger.info(f"Session cleanup: {result}")
+            except Exception as e:
+                logger.debug(f"Session cleanup loop error: {e}")
+
+    session_cleanup_task = asyncio.create_task(session_cleanup_loop())
+
     # Collect DB stats for splash
     auth_stats = auth_service.get_stats()
     db_stats = None
@@ -339,7 +362,8 @@ async def lifespan(app: FastAPI):
     curator_task.cancel()
     precompute_task.cancel()
     consolidation_task.cancel()
-    for task in [queue_task, curator_task, precompute_task, consolidation_task]:
+    session_cleanup_task.cancel()
+    for task in [queue_task, curator_task, precompute_task, consolidation_task, session_cleanup_task]:
         try:
             await task
         except asyncio.CancelledError:
@@ -1661,6 +1685,93 @@ async def _handle_bulk_review_by_type(query, params, session_id):
     )
 
 
+# --- Cross-Session Awareness Skills ---
+
+async def _handle_session_register(query, params, session_id):
+    awareness = get_session_awareness(db)
+    return await awareness.register_session(
+        session_id=session_id or params.get("session_id"),
+        project_path=params.get("project_path", ""),
+        goal=params.get("goal"),
+        label=params.get("label"),
+    )
+
+
+async def _handle_session_heartbeat(query, params, session_id):
+    awareness = get_session_awareness(db)
+    return await awareness.heartbeat(
+        session_id=session_id or params.get("session_id"),
+        project_path=params.get("project_path", ""),
+        files_modified=params.get("files_modified"),
+        current_goal=params.get("current_goal"),
+        key_decisions=params.get("key_decisions"),
+        summary=params.get("summary"),
+    )
+
+
+async def _handle_session_deregister(query, params, session_id):
+    awareness = get_session_awareness(db)
+    return await awareness.deregister_session(
+        session_id=session_id or params.get("session_id"),
+        project_path=params.get("project_path", ""),
+        final_summary=params.get("final_summary"),
+    )
+
+
+async def _handle_get_active_sessions(query, params, session_id):
+    awareness = get_session_awareness(db)
+    sessions = await db.get_active_sessions(
+        project_path=params.get("project_path", ""),
+        exclude_session_id=params.get("exclude_session_id"),
+    )
+    return {"success": True, "sessions": sessions, "count": len(sessions)}
+
+
+async def _handle_session_activity_feed(query, params, session_id):
+    awareness = get_session_awareness(db)
+    return await awareness.get_activity_feed(
+        project_path=params.get("project_path", ""),
+        limit=params.get("limit", 20),
+        since=params.get("since"),
+        exclude_session_id=params.get("exclude_session_id"),
+    )
+
+
+async def _handle_session_catchup(query, params, session_id):
+    awareness = get_session_awareness(db)
+    return await awareness.get_catchup(
+        session_id=session_id or params.get("session_id"),
+        project_path=params.get("project_path", ""),
+        since=params.get("since"),
+    )
+
+
+async def _handle_session_conflicts(query, params, session_id):
+    awareness = get_session_awareness(db)
+    return await awareness.check_conflicts(
+        session_id=session_id or params.get("session_id"),
+        project_path=params.get("project_path", ""),
+    )
+
+
+async def _handle_session_post_activity(query, params, session_id):
+    awareness = get_session_awareness(db)
+    return await awareness.post_activity(
+        session_id=session_id or params.get("session_id"),
+        project_path=params.get("project_path", ""),
+        event_type=params.get("event_type", "decision"),
+        summary=params.get("summary", ""),
+        files=params.get("files"),
+    )
+
+
+async def _handle_session_append_file(query, params, session_id):
+    return await db.append_file_modified(
+        session_id=session_id or params.get("session_id"),
+        file_path=params.get("file_path", ""),
+    )
+
+
 # ============================================================
 # SKILL DISPATCH TABLE
 # ============================================================
@@ -1806,6 +1917,17 @@ SKILL_DISPATCH = {
     "suggest_session_reviews": _handle_suggest_session_reviews,
     "get_recent_sessions": _handle_get_recent_sessions,
     "bulk_review_by_type": _handle_bulk_review_by_type,
+
+    # Cross-Session Awareness
+    "session_register": _handle_session_register,
+    "session_heartbeat": _handle_session_heartbeat,
+    "session_deregister": _handle_session_deregister,
+    "get_active_sessions": _handle_get_active_sessions,
+    "session_activity_feed": _handle_session_activity_feed,
+    "session_catchup": _handle_session_catchup,
+    "session_conflicts": _handle_session_conflicts,
+    "session_post_activity": _handle_session_post_activity,
+    "session_append_file": _handle_session_append_file,
 }
 
 
@@ -5230,6 +5352,129 @@ async def embeddings_migrate_binary_endpoint():
         return {"error": str(e)}
 
 
+# ============================================================
+# CROSS-SESSION AWARENESS REST API
+# ============================================================
+
+@app.post("/api/sessions/register")
+async def api_session_register(request: Request):
+    """Register an active session."""
+    try:
+        body = await request.json()
+        awareness = get_session_awareness(db)
+        return await awareness.register_session(
+            session_id=body.get("session_id", ""),
+            project_path=body.get("project_path", ""),
+            goal=body.get("goal"),
+            label=body.get("label"),
+        )
+    except Exception as e:
+        logger.error(f"Session register failed: {e}")
+        return {"success": False, "error": str(e)}
+
+
+@app.post("/api/sessions/heartbeat")
+async def api_session_heartbeat(request: Request):
+    """Update session heartbeat, return siblings + conflicts."""
+    try:
+        body = await request.json()
+        awareness = get_session_awareness(db)
+        return await awareness.heartbeat(
+            session_id=body.get("session_id", ""),
+            project_path=body.get("project_path", ""),
+            files_modified=body.get("files_modified"),
+            current_goal=body.get("current_goal"),
+            key_decisions=body.get("key_decisions"),
+            summary=body.get("summary"),
+        )
+    except Exception as e:
+        logger.error(f"Session heartbeat failed: {e}")
+        return {"success": False, "error": str(e)}
+
+
+@app.post("/api/sessions/deregister")
+async def api_session_deregister(request: Request):
+    """Mark session as completed."""
+    try:
+        body = await request.json()
+        awareness = get_session_awareness(db)
+        return await awareness.deregister_session(
+            session_id=body.get("session_id", ""),
+            project_path=body.get("project_path", ""),
+            final_summary=body.get("final_summary"),
+        )
+    except Exception as e:
+        logger.error(f"Session deregister failed: {e}")
+        return {"success": False, "error": str(e)}
+
+
+@app.get("/api/sessions/active")
+async def api_active_sessions(project_path: str = "", exclude_session_id: Optional[str] = None):
+    """List active sessions for a project."""
+    try:
+        sessions = await db.get_active_sessions(project_path, exclude_session_id)
+        return {"success": True, "sessions": sessions, "count": len(sessions)}
+    except Exception as e:
+        logger.error(f"Get active sessions failed: {e}")
+        return {"success": False, "error": str(e)}
+
+
+@app.get("/api/sessions/activity-feed")
+async def api_session_activity_feed(
+    project_path: str = "", limit: int = 20,
+    since: Optional[str] = None, exclude_session_id: Optional[str] = None
+):
+    """Get recent cross-session activity events."""
+    try:
+        awareness = get_session_awareness(db)
+        return await awareness.get_activity_feed(project_path, limit, since, exclude_session_id)
+    except Exception as e:
+        logger.error(f"Activity feed failed: {e}")
+        return {"success": False, "error": str(e)}
+
+
+@app.get("/api/sessions/catch-up")
+async def api_session_catchup(
+    session_id: str = "", project_path: str = "", since: Optional[str] = None
+):
+    """What happened since timestamp, grouped by session."""
+    try:
+        awareness = get_session_awareness(db)
+        return await awareness.get_catchup(session_id, project_path, since)
+    except Exception as e:
+        logger.error(f"Session catch-up failed: {e}")
+        return {"success": False, "error": str(e)}
+
+
+@app.get("/api/sessions/conflicts")
+async def api_session_conflicts(session_id: str = "", project_path: str = ""):
+    """Check file conflicts for a session."""
+    try:
+        awareness = get_session_awareness(db)
+        return await awareness.check_conflicts(session_id, project_path)
+    except Exception as e:
+        logger.error(f"Session conflicts failed: {e}")
+        return {"success": False, "error": str(e)}
+
+
+@app.post("/api/sessions/activity")
+async def api_post_session_activity(request: Request):
+    """Post an event to the cross-session activity feed."""
+    try:
+        body = await request.json()
+        awareness = get_session_awareness(db)
+        return await awareness.post_activity(
+            session_id=body.get("session_id", ""),
+            project_path=body.get("project_path", ""),
+            event_type=body.get("event_type", "decision"),
+            summary=body.get("summary", ""),
+            files=body.get("files"),
+        )
+    except Exception as e:
+        logger.error(f"Post session activity failed: {e}")
+        return {"success": False, "error": str(e)}
+
+
 if __name__ == "__main__":
     import uvicorn
     uvicorn.run(

package/mcp_server.py

@@ -445,6 +445,60 @@ async def memory_sync_native(
         return json.dumps({"success": False, "error": str(e)})
 
 
+# ── Cross-Session Awareness Tools ────────────────────────────────────────
+
+@mcp_server.tool()
+async def memory_active_sessions(
+    ctx: Context,
+    project_path: str,
+    exclude_session_id: Optional[str] = None,
+) -> str:
+    """List active parallel Claude Code sessions for a project.
+
+    Use this to see what other sessions are currently working on,
+    what files they've modified, and detect potential conflicts.
+
+    Args:
+        project_path: Project path to check
+        exclude_session_id: Optional session ID to exclude from results
+    """
+    app = _get_app(ctx)
+    sessions = await app.db.get_active_sessions(project_path, exclude_session_id)
+    return json.dumps({
+        "success": True,
+        "sessions": sessions,
+        "count": len(sessions),
+    }, default=str)
+
+
+@mcp_server.tool()
+async def memory_session_catchup(
+    ctx: Context,
+    project_path: str,
+    session_id: Optional[str] = None,
+    since: Optional[str] = None,
+) -> str:
+    """Get a catch-up summary of what other sessions did.
+
+    Returns recent cross-session activity grouped by session,
+    including file changes, decisions, and goals.
+
+    Args:
+        project_path: Project path to check
+        session_id: Current session ID (to exclude own events)
+        since: ISO timestamp to get events after (optional)
+    """
+    app = _get_app(ctx)
+    from services.session_awareness import get_session_awareness
+    awareness = get_session_awareness(app.db)
+    result = await awareness.get_catchup(
+        session_id=session_id or "",
+        project_path=project_path,
+        since=since,
+    )
+    return json.dumps(result, default=str)
+
+
 # ── Entry Point ─────────────────────────────────────────────────────────
 
 if __name__ == "__main__":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-memory-agent",
-  "version": "2.2.2",
+  "version": "2.2.4",
   "description": "Persistent semantic memory system for Claude Code sessions with anti-hallucination grounding",
   "keywords": [
     "claude",

package/services/database.py

@@ -1193,6 +1193,46 @@ class DatabaseService:
         # Migration: Add last_flush_at column to session_state if it doesn't exist
         safe_add_column("session_state", "last_flush_at", "TEXT")
 
+        # ============================================================
+        # CROSS-SESSION AWARENESS TABLES
+        # ============================================================
+
+        # Active sessions - tracks currently running Claude Code sessions
+        cursor.execute("""
+            CREATE TABLE IF NOT EXISTS active_sessions (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                session_id TEXT UNIQUE NOT NULL,
+                project_path TEXT NOT NULL,
+                start_time TEXT DEFAULT (datetime('now')),
+                last_heartbeat TEXT DEFAULT (datetime('now')),
+                current_goal TEXT,
+                status TEXT DEFAULT 'active' CHECK(status IN ('active','idle','completed')),
+                files_modified TEXT DEFAULT '[]',
+                key_decisions TEXT DEFAULT '[]',
+                brief_summary TEXT DEFAULT '',
+                session_label TEXT
+            )
+        """)
+        cursor.execute("CREATE INDEX IF NOT EXISTS idx_active_sessions_project ON active_sessions(project_path, status)")
+        cursor.execute("CREATE INDEX IF NOT EXISTS idx_active_sessions_heartbeat ON active_sessions(last_heartbeat)")
+
+        # Session activity feed - cross-session event stream
+        cursor.execute("""
+            CREATE TABLE IF NOT EXISTS session_activity (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                session_id TEXT NOT NULL,
+                project_path TEXT NOT NULL,
+                event_type TEXT NOT NULL CHECK(event_type IN (
+                    'file_change','decision','error_fix','goal_change','session_start','session_end'
+                )),
+                summary TEXT NOT NULL,
+                files TEXT DEFAULT '[]',
+                timestamp TEXT DEFAULT (datetime('now'))
+            )
+        """)
+        cursor.execute("CREATE INDEX IF NOT EXISTS idx_session_activity_project ON session_activity(project_path, timestamp DESC)")
+        cursor.execute("CREATE INDEX IF NOT EXISTS idx_session_activity_session ON session_activity(session_id, timestamp DESC)")
+
         self.conn.commit()
 
     def _serialize_embedding(self, embedding: List[float]) -> str:
@@ -4116,3 +4156,269 @@ class DatabaseService:
             "most_connected_memories": most_connected,
             "project_path": project_path
         }
+
+    # ============================================================
+    # CROSS-SESSION AWARENESS METHODS
+    # ============================================================
+
+    async def register_active_session(
+        self, session_id: str, project_path: str,
+        goal: Optional[str] = None, label: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """Register a new active session or update if already exists."""
+        project_path = normalize_path(project_path)
+        with self.get_connection() as conn:
+            cursor = conn.cursor()
+            cursor.execute("""
+                INSERT INTO active_sessions (session_id, project_path, current_goal, session_label)
+                VALUES (?, ?, ?, ?)
+                ON CONFLICT(session_id) DO UPDATE SET
+                    status = 'active',
+                    last_heartbeat = datetime('now'),
+                    current_goal = COALESCE(excluded.current_goal, active_sessions.current_goal),
+                    session_label = COALESCE(excluded.session_label, active_sessions.session_label)
+            """, (session_id, project_path, goal, label))
+            conn.commit()
+        return {"success": True, "session_id": session_id}
+
+    async def heartbeat_session(
+        self, session_id: str,
+        files_modified: Optional[List[str]] = None,
+        current_goal: Optional[str] = None,
+        key_decisions: Optional[List[str]] = None,
+        summary: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """Update session heartbeat and optional metadata."""
+        with self.get_connection() as conn:
+            cursor = conn.cursor()
+            updates = ["last_heartbeat = datetime('now')", "status = 'active'"]
+            params = []
+            if files_modified is not None:
+                updates.append("files_modified = ?")
+                params.append(json.dumps(files_modified))
+            if current_goal is not None:
+                updates.append("current_goal = ?")
+                params.append(current_goal)
+            if key_decisions is not None:
+                updates.append("key_decisions = ?")
+                params.append(json.dumps(key_decisions))
+            if summary is not None:
+                updates.append("brief_summary = ?")
+                params.append(summary)
+            params.append(session_id)
+            cursor.execute(
+                f"UPDATE active_sessions SET {', '.join(updates)} WHERE session_id = ?",
+                params
+            )
+            conn.commit()
+        return {"success": True, "updated": cursor.rowcount > 0}
+
+    async def deregister_session(self, session_id: str) -> Dict[str, Any]:
+        """Mark a session as completed."""
+        with self.get_connection() as conn:
+            cursor = conn.cursor()
+            cursor.execute(
+                "UPDATE active_sessions SET status = 'completed', last_heartbeat = datetime('now') WHERE session_id = ?",
+                (session_id,)
+            )
+            conn.commit()
+        return {"success": True, "deregistered": cursor.rowcount > 0}
+
+    async def get_active_sessions(
+        self, project_path: str, exclude_session_id: Optional[str] = None
+    ) -> List[Dict[str, Any]]:
+        """Get active/idle sibling sessions for a project."""
+        project_path = normalize_path(project_path)
+        with self.get_connection() as conn:
+            cursor = conn.cursor()
+            if exclude_session_id:
+                cursor.execute("""
+                    SELECT session_id, project_path, start_time, last_heartbeat,
+                           current_goal, status, files_modified, key_decisions,
+                           brief_summary, session_label
+                    FROM active_sessions
+                    WHERE project_path = ? AND status IN ('active', 'idle')
+                      AND session_id != ?
+                    ORDER BY last_heartbeat DESC
+                """, (project_path, exclude_session_id))
+            else:
+                cursor.execute("""
+                    SELECT session_id, project_path, start_time, last_heartbeat,
+                           current_goal, status, files_modified, key_decisions,
+                           brief_summary, session_label
+                    FROM active_sessions
+                    WHERE project_path = ? AND status IN ('active', 'idle')
+                    ORDER BY last_heartbeat DESC
+                """, (project_path,))
+            rows = cursor.fetchall()
+        return [
+            {
+                "session_id": r["session_id"],
+                "project_path": r["project_path"],
+                "start_time": r["start_time"],
+                "last_heartbeat": r["last_heartbeat"],
+                "current_goal": r["current_goal"],
+                "status": r["status"],
+                "files_modified": json.loads(r["files_modified"] or "[]"),
+                "key_decisions": json.loads(r["key_decisions"] or "[]"),
+                "brief_summary": r["brief_summary"],
+                "session_label": r["session_label"],
+            }
+            for r in rows
+        ]
+
+    async def post_session_activity(
+        self, session_id: str, project_path: str,
+        event_type: str, summary: str, files: Optional[List[str]] = None
+    ) -> Dict[str, Any]:
+        """Post an event to the cross-session activity feed."""
+        project_path = normalize_path(project_path)
+        with self.get_connection() as conn:
+            cursor = conn.cursor()
+            cursor.execute("""
+                INSERT INTO session_activity (session_id, project_path, event_type, summary, files)
+                VALUES (?, ?, ?, ?, ?)
+            """, (session_id, project_path, event_type, summary, json.dumps(files or [])))
+            conn.commit()
+        return {"success": True, "id": cursor.lastrowid}
+
+    async def get_session_activity_feed(
+        self, project_path: str, limit: int = 20,
+        since: Optional[str] = None, exclude_session_id: Optional[str] = None
+    ) -> List[Dict[str, Any]]:
+        """Get recent cross-session activity events."""
+        project_path = normalize_path(project_path)
+        with self.get_connection() as conn:
+            cursor = conn.cursor()
+            query = "SELECT * FROM session_activity WHERE project_path = ?"
+            params: list = [project_path]
+            if since:
+                query += " AND timestamp > ?"
+                params.append(since)
+            if exclude_session_id:
+                query += " AND session_id != ?"
+                params.append(exclude_session_id)
+            query += " ORDER BY timestamp DESC LIMIT ?"
+            params.append(limit)
+            cursor.execute(query, params)
+            rows = cursor.fetchall()
+        return [
+            {
+                "id": r["id"],
+                "session_id": r["session_id"],
+                "project_path": r["project_path"],
+                "event_type": r["event_type"],
+                "summary": r["summary"],
+                "files": json.loads(r["files"] or "[]"),
+                "timestamp": r["timestamp"],
+            }
+            for r in rows
+        ]
+
+    async def detect_file_conflicts(
+        self, session_id: str, project_path: str
+    ) -> List[Dict[str, Any]]:
+        """Detect file conflicts between this session and active siblings."""
+        project_path = normalize_path(project_path)
+        with self.get_connection() as conn:
+            cursor = conn.cursor()
+            # Get this session's files
+            cursor.execute(
+                "SELECT files_modified FROM active_sessions WHERE session_id = ?",
+                (session_id,)
+            )
+            row = cursor.fetchone()
+            if not row:
+                return []
+            my_files = set(json.loads(row["files_modified"] or "[]"))
+            if not my_files:
+                return []
+
+            # Get sibling sessions' files
+            cursor.execute("""
+                SELECT session_id, files_modified, session_label, current_goal
+                FROM active_sessions
+                WHERE project_path = ? AND status IN ('active', 'idle')
+                  AND session_id != ?
+            """, (project_path, session_id))
+            siblings = cursor.fetchall()
+
+        conflicts = []
+        for sib in siblings:
+            sib_files = set(json.loads(sib["files_modified"] or "[]"))
+            overlap = my_files & sib_files
+            if overlap:
+                conflicts.append({
+                    "session_id": sib["session_id"],
+                    "session_label": sib["session_label"],
+                    "current_goal": sib["current_goal"],
+                    "conflicting_files": sorted(overlap),
+                })
+        return conflicts
+
+    async def cleanup_stale_sessions(
+        self, idle_minutes: int = 10, completed_minutes: int = 30
+    ) -> Dict[str, Any]:
+        """Mark stale sessions as idle/completed and clean up old activity."""
+        with self.get_connection() as conn:
+            cursor = conn.cursor()
+            # Mark active sessions with no heartbeat as idle
+            cursor.execute("""
+                UPDATE active_sessions SET status = 'idle'
+                WHERE status = 'active'
+                  AND last_heartbeat < datetime('now', ? || ' minutes')
+            """, (f"-{idle_minutes}",))
+            marked_idle = cursor.rowcount
+
+            # Mark idle sessions as completed after longer timeout
+            cursor.execute("""
+                UPDATE active_sessions SET status = 'completed'
+                WHERE status = 'idle'
+                  AND last_heartbeat < datetime('now', ? || ' minutes')
+            """, (f"-{completed_minutes}",))
+            marked_completed = cursor.rowcount
+
+            # Delete old completed sessions (older than 24h)
+            cursor.execute("""
+                DELETE FROM active_sessions
+                WHERE status = 'completed'
+                  AND last_heartbeat < datetime('now', '-24 hours')
+            """)
+            deleted_sessions = cursor.rowcount
+
+            # Delete old activity events (older than configured max age)
+            cursor.execute("""
+                DELETE FROM session_activity
+                WHERE timestamp < datetime('now', '-24 hours')
+            """)
+            deleted_events = cursor.rowcount
+
+            conn.commit()
+        return {
+            "marked_idle": marked_idle,
+            "marked_completed": marked_completed,
+            "deleted_sessions": deleted_sessions,
+            "deleted_events": deleted_events,
+        }
+
+    async def append_file_modified(self, session_id: str, file_path: str) -> Dict[str, Any]:
+        """Atomically append a file to a session's files_modified list."""
+        file_path = normalize_path(file_path)
+        with self.get_connection() as conn:
+            cursor = conn.cursor()
+            cursor.execute(
+                "SELECT files_modified FROM active_sessions WHERE session_id = ?",
+                (session_id,)
+            )
+            row = cursor.fetchone()
+            if not row:
+                return {"success": False, "error": "Session not found"}
+            files = json.loads(row["files_modified"] or "[]")
+            if file_path not in files:
+                files.append(file_path)
+                cursor.execute(
+                    "UPDATE active_sessions SET files_modified = ? WHERE session_id = ?",
+                    (json.dumps(files), session_id)
+                )
+                conn.commit()
+        return {"success": True, "files_count": len(files)}