ivas 0.1.0__py3-none-any.whl

ivas/__init__.py

@@ -0,0 +1,27 @@
+"""
+IVAS -- Immortal Virtual Agent Sessions.
+
+Persistent memory and session continuity for any AI agent.
+Your agent remembers everything. Forever. Across crashes, restarts, and updates.
+
+Quick start:
+    from ivas import Brain
+
+    brain = Brain("my-agent")
+    brain.remember("user", "preferences", "User prefers dark mode")
+    results = brain.recall("dark mode")
+
+Patent: 64/019,813 (Provisional) -- Multi-Instance AI Agent Session Relay System
+              with Persistent State Recovery
+"""
+
+__version__ = "0.1.0"
+__author__ = "Arvind Ramamoorthy"
+
+from ivas.brain import Brain
+from ivas.session import Session
+from ivas.manifest import RecallManifest
+from ivas.corrections import Corrections
+from ivas.einherjar import Einherjar
+
+__all__ = ["Brain", "Session", "RecallManifest", "Corrections", "Einherjar"]

ivas/brain.py

@@ -0,0 +1,406 @@
+"""
+IVAS Brain -- Persistent memory with full-text search.
+
+SQLite + FTS5 for zero-dependency, cross-platform, crash-proof memory.
+No MongoDB. No Redis. No Docker. One file. Works everywhere.
+
+Usage:
+    brain = Brain("my-agent")
+    brain.remember("meeting", "standup", "Decided to ship v2 Friday")
+    brain.recall("ship v2")  # -> list of memories
+    brain.forget(memory_id)  # -> remove a memory
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+
+@dataclass
+class Memory:
+    """A single memory entry."""
+    id: int
+    category: str
+    subject: str
+    content: str
+    confidence: float
+    created_at: float
+    source: Optional[str] = None
+    metadata: dict = field(default_factory=dict)
+
+    def age_hours(self) -> float:
+        return (time.time() - self.created_at) / 3600
+
+    def age_days(self) -> float:
+        return self.age_hours() / 24
+
+
+class Brain:
+    """Persistent memory store with full-text search.
+
+    Each agent gets its own SQLite database. Memories are categorized,
+    full-text searchable, and survive crashes, restarts, and updates.
+
+    Args:
+        agent_id: Unique identifier for this agent (used as DB filename).
+        data_dir: Directory to store the database. Defaults to ~/.ivas/
+        auto_vacuum: Run SQLite VACUUM on open (default False).
+    """
+
+    def __init__(
+        self,
+        agent_id: str,
+        data_dir: Optional[str | Path] = None,
+        auto_vacuum: bool = False,
+    ):
+        self.agent_id = agent_id
+        self.data_dir = Path(data_dir) if data_dir else Path.home() / ".ivas"
+        self.data_dir.mkdir(parents=True, exist_ok=True)
+        self.db_path = self.data_dir / f"{agent_id}.db"
+        self._conn = self._connect(auto_vacuum)
+        self._setup_tables()
+
+    def _connect(self, auto_vacuum: bool) -> sqlite3.Connection:
+        conn = sqlite3.connect(str(self.db_path), timeout=10)
+        conn.execute("PRAGMA journal_mode=WAL")
+        conn.execute("PRAGMA synchronous=NORMAL")
+        conn.execute("PRAGMA busy_timeout=5000")
+        if auto_vacuum:
+            conn.execute("VACUUM")
+        return conn
+
+    def _setup_tables(self):
+        self._conn.executescript("""
+            CREATE TABLE IF NOT EXISTS memories (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                category TEXT NOT NULL,
+                subject TEXT NOT NULL,
+                content TEXT NOT NULL,
+                confidence REAL DEFAULT 0.8,
+                source TEXT,
+                metadata TEXT DEFAULT '{}',
+                created_at REAL NOT NULL,
+                updated_at REAL
+            );
+
+            CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
+                category, subject, content,
+                content='memories',
+                content_rowid='id',
+                tokenize='porter unicode61'
+            );
+
+            CREATE TRIGGER IF NOT EXISTS memories_ai AFTER INSERT ON memories BEGIN
+                INSERT INTO memories_fts(rowid, category, subject, content)
+                VALUES (new.id, new.category, new.subject, new.content);
+            END;
+
+            CREATE TRIGGER IF NOT EXISTS memories_ad AFTER DELETE ON memories BEGIN
+                INSERT INTO memories_fts(memories_fts, rowid, category, subject, content)
+                VALUES ('delete', old.id, old.category, old.subject, old.content);
+            END;
+
+            CREATE TRIGGER IF NOT EXISTS memories_au AFTER UPDATE ON memories BEGIN
+                INSERT INTO memories_fts(memories_fts, rowid, category, subject, content)
+                VALUES ('delete', old.id, old.category, old.subject, old.content);
+                INSERT INTO memories_fts(rowid, category, subject, content)
+                VALUES (new.id, new.category, new.subject, new.content);
+            END;
+
+            CREATE INDEX IF NOT EXISTS idx_memories_category ON memories(category);
+            CREATE INDEX IF NOT EXISTS idx_memories_created ON memories(created_at);
+        """)
+        self._conn.commit()
+
+    def remember(
+        self,
+        category: str,
+        subject: str,
+        content: str,
+        confidence: float = 0.8,
+        source: Optional[str] = None,
+        metadata: Optional[dict] = None,
+    ) -> int:
+        """Store a memory. Returns the memory ID.
+
+        Args:
+            category: High-level category (e.g., "user", "decision", "error").
+            subject: Specific topic (e.g., "dark_mode_preference").
+            content: The actual memory content.
+            confidence: How confident you are (0.0 to 1.0).
+            source: Where this memory came from (optional).
+            metadata: Additional key-value data (optional).
+
+        Returns:
+            The integer ID of the stored memory.
+        """
+        now = time.time()
+        cursor = self._conn.execute(
+            """INSERT INTO memories (category, subject, content, confidence, source, metadata, created_at)
+               VALUES (?, ?, ?, ?, ?, ?, ?)""",
+            (category, subject, content, confidence, source,
+             json.dumps(metadata or {}), now),
+        )
+        self._conn.commit()
+        return cursor.lastrowid
+
+    # Stopwords to skip when building auto OR-join queries
+    _STOPWORDS = frozenset({
+        "a", "an", "the", "is", "are", "was", "were", "be", "been", "being",
+        "have", "has", "had", "do", "does", "did", "will", "would", "shall",
+        "should", "may", "might", "can", "could", "to", "of", "in", "for",
+        "on", "with", "at", "by", "from", "as", "into", "about", "that",
+        "this", "it", "its", "i", "you", "he", "she", "we", "they", "my",
+        "your", "his", "her", "our", "their", "what", "which", "who", "whom",
+        "when", "where", "how", "why", "not", "no", "and", "or", "but", "if",
+        "so", "than", "too", "very", "just", "also", "then", "there", "here",
+    })
+
+    @staticmethod
+    def _is_explicit_fts5(query: str) -> bool:
+        """Return True if the query already contains explicit FTS5 syntax."""
+        import re
+        # Explicit FTS5 markers: OR / AND / NOT (uppercase), quoted phrases
+        return bool(re.search(r'\bOR\b|\bAND\b|\bNOT\b|"', query))
+
+    def _sanitize_query(self, query: str) -> str:
+        """Convert a plain natural-language query into an FTS5 OR-joined query.
+
+        If the query already uses explicit FTS5 syntax (OR, AND, NOT, quotes)
+        it is returned unchanged.  Otherwise punctuation is stripped, stopwords
+        are removed, and the remaining content words are joined with OR so that
+        multi-word queries like "notification preference" find memories that
+        mention either word.
+        """
+        import re
+        if self._is_explicit_fts5(query):
+            return query
+        # Strip punctuation, keep word characters and spaces
+        clean = re.sub(r'[^\w\s]', ' ', query)
+        words = [
+            w for w in clean.split()
+            if len(w) > 2 and w.lower() not in self._STOPWORDS
+        ]
+        if not words:
+            # Fallback: use cleaned query as-is to avoid empty MATCH
+            return re.sub(r'[^\w\s]', ' ', query).strip() or query
+        return " OR ".join(words)
+
+    def recall(
+        self,
+        query: str,
+        limit: int = 10,
+        category: Optional[str] = None,
+        min_confidence: float = 0.0,
+    ) -> list[Memory]:
+        """Search memories using full-text search.
+
+        Args:
+            query: Search query (supports FTS5 syntax: AND, OR, NOT, quotes).
+                   Plain natural-language queries are automatically OR-joined
+                   so that partial matches are returned.
+            limit: Maximum results to return.
+            category: Filter to this category only (optional).
+            min_confidence: Minimum confidence threshold.
+
+        Returns:
+            List of Memory objects, ranked by relevance then recency.
+        """
+        # Sanitize plain queries into FTS5 OR-join; pass explicit syntax through
+        fts_query = self._sanitize_query(query)
+
+        # Build FTS query with optional category filter
+        params: list = []
+        sql = """
+            SELECT m.id, m.category, m.subject, m.content, m.confidence,
+                   m.created_at, m.source, m.metadata,
+                   rank
+            FROM memories_fts fts
+            JOIN memories m ON m.id = fts.rowid
+            WHERE memories_fts MATCH ?
+        """
+        params.append(fts_query)
+
+        if category:
+            sql += " AND m.category = ?"
+            params.append(category)
+
+        if min_confidence > 0:
+            sql += " AND m.confidence >= ?"
+            params.append(min_confidence)
+
+        # Primary sort: FTS5 rank (more negative = more relevant).
+        # Tiebreaker: newest memory first, so corrections/updates surface above
+        # older entries when relevance scores are equal.
+        sql += " ORDER BY rank, m.created_at DESC LIMIT ?"
+        params.append(limit)
+
+        rows = self._conn.execute(sql, params).fetchall()
+        return [self._row_to_memory(r) for r in rows]
+
+    def get(self, memory_id: int) -> Optional[Memory]:
+        """Get a specific memory by ID."""
+        row = self._conn.execute(
+            """SELECT id, category, subject, content, confidence,
+                      created_at, source, metadata, 0 as rank
+               FROM memories WHERE id = ?""",
+            (memory_id,),
+        ).fetchone()
+        return self._row_to_memory(row) if row else None
+
+    def update(
+        self,
+        memory_id: int,
+        content: Optional[str] = None,
+        confidence: Optional[float] = None,
+        metadata: Optional[dict] = None,
+    ) -> bool:
+        """Update an existing memory. Returns True if found and updated."""
+        existing = self.get(memory_id)
+        if not existing:
+            return False
+
+        updates = []
+        params = []
+        if content is not None:
+            updates.append("content = ?")
+            params.append(content)
+        if confidence is not None:
+            updates.append("confidence = ?")
+            params.append(confidence)
+        if metadata is not None:
+            updates.append("metadata = ?")
+            params.append(json.dumps(metadata))
+
+        if not updates:
+            return True
+
+        updates.append("updated_at = ?")
+        params.append(time.time())
+        params.append(memory_id)
+
+        self._conn.execute(
+            f"UPDATE memories SET {', '.join(updates)} WHERE id = ?",
+            params,
+        )
+        self._conn.commit()
+        return True
+
+    def forget(self, memory_id: int) -> bool:
+        """Delete a memory. Returns True if it existed."""
+        cursor = self._conn.execute(
+            "DELETE FROM memories WHERE id = ?", (memory_id,)
+        )
+        self._conn.commit()
+        return cursor.rowcount > 0
+
+    def recent(self, limit: int = 20, category: Optional[str] = None) -> list[Memory]:
+        """Get the most recent memories."""
+        if category:
+            rows = self._conn.execute(
+                """SELECT id, category, subject, content, confidence,
+                          created_at, source, metadata, 0 as rank
+                   FROM memories WHERE category = ?
+                   ORDER BY created_at DESC LIMIT ?""",
+                (category, limit),
+            ).fetchall()
+        else:
+            rows = self._conn.execute(
+                """SELECT id, category, subject, content, confidence,
+                          created_at, source, metadata, 0 as rank
+                   FROM memories ORDER BY created_at DESC LIMIT ?""",
+                (limit,),
+            ).fetchall()
+        return [self._row_to_memory(r) for r in rows]
+
+    def stats(self) -> dict:
+        """Get memory statistics."""
+        total = self._conn.execute("SELECT COUNT(*) FROM memories").fetchone()[0]
+        categories = self._conn.execute(
+            "SELECT category, COUNT(*) FROM memories GROUP BY category ORDER BY COUNT(*) DESC"
+        ).fetchall()
+        oldest = self._conn.execute(
+            "SELECT MIN(created_at) FROM memories"
+        ).fetchone()[0]
+        newest = self._conn.execute(
+            "SELECT MAX(created_at) FROM memories"
+        ).fetchone()[0]
+
+        return {
+            "agent_id": self.agent_id,
+            "total_memories": total,
+            "categories": {c: n for c, n in categories},
+            "oldest_memory": oldest,
+            "newest_memory": newest,
+            "db_path": str(self.db_path),
+            "db_size_mb": round(self.db_path.stat().st_size / 1024 / 1024, 2),
+        }
+
+    def export(self, path: Optional[str | Path] = None) -> str:
+        """Export all memories to JSON. Returns the JSON string."""
+        rows = self._conn.execute(
+            """SELECT id, category, subject, content, confidence,
+                      created_at, source, metadata
+               FROM memories ORDER BY created_at"""
+        ).fetchall()
+        memories = []
+        for r in rows:
+            memories.append({
+                "id": r[0], "category": r[1], "subject": r[2],
+                "content": r[3], "confidence": r[4], "created_at": r[5],
+                "source": r[6], "metadata": json.loads(r[7] or "{}"),
+            })
+        data = json.dumps({"agent_id": self.agent_id, "memories": memories}, indent=2)
+        if path:
+            Path(path).write_text(data)
+        return data
+
+    def import_from(self, path: str | Path) -> int:
+        """Import memories from a JSON export. Returns count imported."""
+        data = json.loads(Path(path).read_text())
+        count = 0
+        for m in data.get("memories", []):
+            self.remember(
+                category=m["category"],
+                subject=m["subject"],
+                content=m["content"],
+                confidence=m.get("confidence", 0.8),
+                source=m.get("source"),
+                metadata=m.get("metadata"),
+            )
+            count += 1
+        return count
+
+    def close(self):
+        """Close the database connection."""
+        self._conn.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+    def __len__(self) -> int:
+        return self._conn.execute("SELECT COUNT(*) FROM memories").fetchone()[0]
+
+    def __repr__(self) -> str:
+        return f"Brain(agent_id={self.agent_id!r}, memories={len(self)}, db={self.db_path})"
+
+    @staticmethod
+    def _row_to_memory(row) -> Memory:
+        return Memory(
+            id=row[0],
+            category=row[1],
+            subject=row[2],
+            content=row[3],
+            confidence=row[4],
+            created_at=row[5],
+            source=row[6],
+            metadata=json.loads(row[7] or "{}"),
+        )

ivas/cli.py

@@ -0,0 +1,179 @@
+"""
+IVAS CLI -- Command-line interface for IVAS.
+
+Usage:
+    ivas remember <category> <subject> <content>
+    ivas recall <query>
+    ivas stats
+    ivas export [--output <path>]
+    ivas import <path>
+    ivas session restore
+    ivas session save <task> [<thought>]
+    ivas version
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+
+from ivas.brain import Brain
+from ivas.session import Session
+
+
+def _get_brain(args) -> Brain:
+    agent_id = getattr(args, "agent", None) or "default"
+    data_dir = getattr(args, "data_dir", None)
+    return Brain(agent_id, data_dir=data_dir)
+
+
+def cmd_remember(args):
+    brain = _get_brain(args)
+    mem_id = brain.remember(args.category, args.subject, args.content)
+    print(f"Remembered #{mem_id}: [{args.category}] {args.subject}")
+    brain.close()
+
+
+def cmd_recall(args):
+    brain = _get_brain(args)
+    results = brain.recall(args.query, limit=args.limit)
+    if not results:
+        print("No memories found.")
+    else:
+        for m in results:
+            age = m.age_hours()
+            age_str = f"{age:.1f}h" if age < 24 else f"{age/24:.1f}d"
+            print(f"  [{m.id}] {m.category}/{m.subject} ({age_str} ago)")
+            print(f"       {m.content[:120]}")
+            print()
+    brain.close()
+
+
+def cmd_stats(args):
+    brain = _get_brain(args)
+    stats = brain.stats()
+    print(f"Agent: {stats['agent_id']}")
+    print(f"Total memories: {stats['total_memories']}")
+    print(f"Database: {stats['db_path']} ({stats['db_size_mb']} MB)")
+    if stats['categories']:
+        print("Categories:")
+        for cat, count in stats['categories'].items():
+            print(f"  {cat}: {count}")
+    brain.close()
+
+
+def cmd_export(args):
+    brain = _get_brain(args)
+    output = args.output or f"{brain.agent_id}_export.json"
+    data = brain.export(output)
+    count = len(json.loads(data).get("memories", []))
+    print(f"Exported {count} memories to {output}")
+    brain.close()
+
+
+def cmd_import(args):
+    brain = _get_brain(args)
+    count = brain.import_from(args.path)
+    print(f"Imported {count} memories from {args.path}")
+    brain.close()
+
+
+def cmd_session_save(args):
+    brain = _get_brain(args)
+    session = Session(brain.agent_id, brain=brain)
+    state = session.save_state(
+        active_task=args.task,
+        current_thought=args.thought,
+    )
+    print(f"State saved: {state.active_task}")
+    brain.close()
+
+
+def cmd_session_restore(args):
+    brain = _get_brain(args)
+    session = Session(brain.agent_id, brain=brain)
+    state = session.restore()
+    if state:
+        print(f"Restored from: {state.restored_from}")
+        print(f"Active task: {state.active_task}")
+        print(f"Current thought: {state.current_thought}")
+        print(f"Decisions: {json.dumps(state.decisions, indent=2)}")
+        print(f"Pending: {state.pending_actions}")
+        age = state.age_seconds()
+        print(f"Age: {age:.0f}s ({age/3600:.1f}h)")
+    else:
+        print("No prior state found.")
+    brain.close()
+
+
+def cmd_version(_args):
+    from ivas import __version__
+    print(f"ivas {__version__}")
+
+
+def main(argv: list[str] | None = None):
+    parser = argparse.ArgumentParser(
+        prog="ivas",
+        description="IVAS -- Immortal Virtual Agent Sessions",
+    )
+    parser.add_argument("--agent", "-a", default="default", help="Agent ID")
+    parser.add_argument("--data-dir", "-d", help="Data directory (default: ~/.ivas/)")
+
+    sub = parser.add_subparsers(dest="command")
+
+    # remember
+    p_rem = sub.add_parser("remember", help="Store a memory")
+    p_rem.add_argument("category")
+    p_rem.add_argument("subject")
+    p_rem.add_argument("content")
+
+    # recall
+    p_rec = sub.add_parser("recall", help="Search memories")
+    p_rec.add_argument("query")
+    p_rec.add_argument("--limit", "-n", type=int, default=10)
+
+    # stats
+    sub.add_parser("stats", help="Show memory statistics")
+
+    # export
+    p_exp = sub.add_parser("export", help="Export memories to JSON")
+    p_exp.add_argument("--output", "-o")
+
+    # import
+    p_imp = sub.add_parser("import", help="Import memories from JSON")
+    p_imp.add_argument("path")
+
+    # session save
+    p_ss = sub.add_parser("save", help="Save session state")
+    p_ss.add_argument("task", help="Current task description")
+    p_ss.add_argument("thought", nargs="?", help="Current thought")
+
+    # session restore
+    sub.add_parser("restore", help="Restore last session state")
+
+    # version
+    sub.add_parser("version", help="Show version")
+
+    args = parser.parse_args(argv)
+
+    commands = {
+        "remember": cmd_remember,
+        "recall": cmd_recall,
+        "stats": cmd_stats,
+        "export": cmd_export,
+        "import": cmd_import,
+        "save": cmd_session_save,
+        "restore": cmd_session_restore,
+        "version": cmd_version,
+    }
+
+    if args.command in commands:
+        commands[args.command](args)
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()