memorytrace 0.1.0__py3-none-any.whl

engram/session/__init__.py

@@ -0,0 +1,6 @@
+"""Session management for Engram."""
+
+from engram.session.manager import SessionManager
+from engram.session.working_memory import WorkingMemory
+
+__all__ = ["SessionManager", "WorkingMemory"]

engram/session/context.py

@@ -0,0 +1,87 @@
+"""Context carryover between sessions — resolves IDs to names, aggregates history."""
+
+from __future__ import annotations
+
+from collections import Counter
+from typing import Optional
+
+from engram.storage.base import StorageBackend
+
+
+def build_session_context(storage: StorageBackend, agent_id: str, session_limit: int = 5) -> dict:
+    """Build a rich context summary for the start of a new session.
+
+    Looks at the last N sessions (not just 1) to aggregate knowledge.
+    Resolves entity IDs to human-readable names.
+    """
+    recent = storage.get_recent_sessions(agent_id, limit=session_limit)
+
+    context: dict = {
+        "entity_count": storage.entity_count(),
+        "fact_count": storage.fact_count(),
+        "pending_conflicts": len(storage.get_pending_conflicts()),
+    }
+
+    if not recent:
+        context["previous_summary"] = ""
+        context["previous_entities"] = []
+        context["recent_topics"] = []
+        context["sessions_reviewed"] = 0
+        return context
+
+    # Last completed session's summary
+    last_completed = None
+    for s in recent:
+        if s.ended_at:
+            last_completed = s
+            break
+
+    context["previous_summary"] = last_completed.summary if last_completed and last_completed.summary else ""
+
+    # Aggregate entity access across recent sessions — resolve IDs to names
+    entity_access_count: Counter = Counter()
+    for s in recent:
+        if s.ended_at:
+            for eid in s.entities_accessed:
+                entity_access_count[eid] += 1
+
+    # Resolve top entity IDs to names
+    top_entity_ids = [eid for eid, _ in entity_access_count.most_common(15)]
+    resolved_entities: list[dict] = []
+    for eid in top_entity_ids:
+        entity = storage.get_entity(eid)
+        if entity:
+            resolved_entities.append({
+                "name": entity.name,
+                "type": entity.entity_type,
+                "access_count": entity_access_count[eid],
+            })
+
+    context["previous_entities"] = [e["name"] for e in resolved_entities]
+    context["recent_entity_details"] = resolved_entities
+
+    # Include top facts for the most important entities (actual knowledge, not just names)
+    key_facts: list[dict] = []
+    for entity_info in resolved_entities[:5]:
+        eid = next((eid for eid, _ in entity_access_count.most_common(15)
+                     if storage.get_entity(eid) and storage.get_entity(eid).name == entity_info["name"]), None)
+        if eid:
+            facts = storage.get_current_facts(eid)
+            top_facts = sorted(facts, key=lambda f: f.confidence, reverse=True)[:3]
+            for f in top_facts:
+                key_facts.append({
+                    "entity": entity_info["name"],
+                    "fact": f.raw_text,
+                    "confidence": f.confidence,
+                })
+    context["key_facts"] = key_facts
+
+    # Collect recent topics from session summaries
+    recent_topics: list[str] = []
+    for s in recent:
+        if s.ended_at and s.summary:
+            recent_topics.append(s.summary)
+    context["recent_topics"] = recent_topics[:5]
+    context["sessions_reviewed"] = len([s for s in recent if s.ended_at])
+
+    return context

engram/session/manager.py

@@ -0,0 +1,152 @@
+"""Session lifecycle management."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+from typing import Optional
+
+from engram.exceptions import SessionError
+from engram.models.session import Session, SessionEvent
+from engram.storage.base import StorageBackend
+
+
+class SessionManager:
+    """Manages session lifecycle: start, track events, end, and context carryover."""
+
+    def __init__(self, storage: StorageBackend):
+        self.storage = storage
+        self._active: dict[str, Session] = {}
+
+    def start_session(self, agent_id: str = "default") -> Session:
+        """Start a new session, linking to the previous one."""
+        previous = self.storage.get_recent_sessions(agent_id, limit=1)
+        session = Session(
+            session_id=str(uuid.uuid4()),
+            agent_id=agent_id,
+            started_at=datetime.now(),
+            parent_session_id=previous[0].session_id if previous else None,
+        )
+        self.storage.save_session(session)
+        self._active[session.session_id] = session
+        return session
+
+    def end_session(self, session_id: str, summary: Optional[str] = None) -> Session:
+        """End a session and persist it. Auto-generates summary if not provided."""
+        session = self._active.pop(session_id, None)
+        if session is None:
+            session = self.storage.get_session(session_id)
+        if session is None:
+            raise SessionError(f"Session {session_id} not found")
+
+        session.ended_at = datetime.now()
+        if summary:
+            session.summary = summary
+        elif not session.summary:
+            session.summary = self._auto_summary(session)
+        self.storage.save_session(session)
+        return session
+
+    def _auto_summary(self, session: Session) -> str:
+        """Auto-generate summary from session tracking data."""
+        parts: list[str] = []
+        if session.entities_modified:
+            names: list[str] = []
+            for eid in session.entities_modified[:5]:
+                entity = self.storage.get_entity(eid)
+                if entity:
+                    names.append(entity.name)
+            if names:
+                parts.append(f"Modified: {', '.join(names)}")
+        if session.entities_accessed:
+            accessed_names: list[str] = []
+            for eid in session.entities_accessed[:5]:
+                if eid not in (session.entities_modified or []):
+                    entity = self.storage.get_entity(eid)
+                    if entity:
+                        accessed_names.append(entity.name)
+            if accessed_names:
+                parts.append(f"Discussed: {', '.join(accessed_names)}")
+        if session.facts_added:
+            parts.append(f"{len(session.facts_added)} facts added")
+        return ". ".join(parts) if parts else "Session with no significant changes"
+
+    def get_active_session(self, session_id: str) -> Optional[Session]:
+        """Get an active session by ID."""
+        return self._active.get(session_id)
+
+    def record_entity_access(self, session_id: str, entity_id: str) -> None:
+        """Record that an entity was accessed in this session."""
+        session = self._active.get(session_id)
+        if session and entity_id not in session.entities_accessed:
+            session.entities_accessed.append(entity_id)
+
+    def record_entity_modified(self, session_id: str, entity_id: str) -> None:
+        """Record that an entity was modified in this session."""
+        session = self._active.get(session_id)
+        if session:
+            if entity_id not in session.entities_modified:
+                session.entities_modified.append(entity_id)
+            if entity_id not in session.entities_accessed:
+                session.entities_accessed.append(entity_id)
+
+    def record_fact_added(self, session_id: str, fact_id: str) -> None:
+        """Record that a fact was added in this session."""
+        session = self._active.get(session_id)
+        if session:
+            session.facts_added.append(fact_id)
+
+    def log_event(self, session_id: str, event_type: str, target: str = "", detail: Optional[dict] = None) -> None:
+        """Log an auditable event within a session."""
+        event = SessionEvent(
+            session_id=session_id,
+            event_type=event_type,
+            target=target,
+            detail=detail or {},
+            timestamp=datetime.now(),
+        )
+        self.storage.add_session_event(event)
+
+    def get_context_carryover(self, agent_id: str) -> str:
+        """Generate context string from recent sessions for system prompt injection.
+
+        Resolves entity IDs to names for agent readability.
+        Looks at last 3 completed sessions, not just 1.
+        """
+        recent = self.storage.get_recent_sessions(agent_id, limit=5)
+        completed = [s for s in recent if s.ended_at]
+        if not completed:
+            return ""
+
+        parts = []
+
+        # Last session summary
+        if completed[0].summary:
+            parts.append(f"Previous session: {completed[0].summary}")
+
+        # Resolve entity IDs to names across recent sessions
+        all_entity_ids: list[str] = []
+        for s in completed[:3]:
+            all_entity_ids.extend(s.entities_accessed)
+        # Deduplicate preserving order
+        seen: set[str] = set()
+        unique_ids: list[str] = []
+        for eid in all_entity_ids:
+            if eid not in seen:
+                seen.add(eid)
+                unique_ids.append(eid)
+
+        entity_names: list[str] = []
+        for eid in unique_ids[:10]:
+            entity = self.storage.get_entity(eid)
+            if entity:
+                entity_names.append(entity.name)
+
+        if entity_names:
+            parts.append(f"Recently discussed: {', '.join(entity_names)}")
+
+        total_facts = sum(len(s.facts_added) for s in completed[:3])
+        if total_facts:
+            parts.append(f"Facts added recently: {total_facts}")
+
+        return " | ".join(parts) if parts else ""

engram/session/working_memory.py

@@ -0,0 +1,57 @@
+"""Working memory — short-term context within a single session."""
+
+from __future__ import annotations
+
+from engram.models.session import Session
+from engram.storage.base import StorageBackend
+
+
+class WorkingMemory:
+    """Short-term memory within a single session.
+
+    Tracks active entities and recent queries to provide
+    context-aware search boosting and reference resolution.
+    """
+
+    def __init__(self, session: Session):
+        self.session = session
+        self.active_entities: list[str] = []  # entity IDs, most recent first
+        self.recent_queries: list[str] = []
+        self.facts_added_count: int = 0
+
+    def touch_entity(self, entity_id: str) -> None:
+        """Mark entity as active in this session (most recent first)."""
+        if entity_id in self.active_entities:
+            self.active_entities.remove(entity_id)
+        self.active_entities.insert(0, entity_id)
+
+    def get_active_entity_ids(self, limit: int = 5) -> list[str]:
+        """Return the most recently accessed entity IDs."""
+        return self.active_entities[:limit]
+
+    def add_query(self, query: str) -> None:
+        """Record a search query."""
+        self.recent_queries.insert(0, query)
+        if len(self.recent_queries) > 20:
+            self.recent_queries = self.recent_queries[:20]
+
+    def get_active_context(self, storage: StorageBackend, max_tokens: int = 300) -> str:
+        """Return compact summary of what's been discussed in this session."""
+        parts: list[str] = []
+        tokens_used = 0
+
+        for eid in self.active_entities[:5]:
+            entity = storage.get_entity(eid)
+            if entity:
+                entry = f"{entity.name}"
+                if entity.state.role:
+                    entry += f" ({entity.state.role})"
+                entry_tokens = len(entry) // 4
+                if tokens_used + entry_tokens > max_tokens:
+                    break
+                parts.append(entry)
+                tokens_used += entry_tokens
+
+        if not parts:
+            return ""
+        return "Active context: " + ", ".join(parts)

engram/storage/__init__.py

@@ -0,0 +1,6 @@
+"""Storage backends for Engram."""
+
+from engram.storage.base import StorageBackend
+from engram.storage.sqlite_store import SQLiteStorage
+
+__all__ = ["StorageBackend", "SQLiteStorage"]

engram/storage/base.py

@@ -0,0 +1,63 @@
+"""Storage backend protocol — the contract all backends must implement."""
+
+from __future__ import annotations
+
+from typing import Optional, Protocol, runtime_checkable
+
+from engram.models.entity import Entity, Tier
+from engram.models.fact import Fact, FactStatus
+from engram.models.relation import Relation
+from engram.models.session import Session, SessionEvent
+
+
+@runtime_checkable
+class StorageBackend(Protocol):
+    """Abstract storage interface."""
+
+    def initialize(self) -> None: ...
+    def close(self) -> None: ...
+
+    # Entity CRUD
+    def create_entity(self, entity: Entity) -> Entity: ...
+    def get_entity(self, entity_id: str) -> Optional[Entity]: ...
+    def get_entity_by_name(self, name: str) -> Optional[Entity]: ...
+    def update_entity(self, entity: Entity) -> Entity: ...
+    def delete_entity(self, entity_id: str) -> bool: ...
+    def list_entities(
+        self,
+        tier: Optional[Tier] = None,
+        entity_type: Optional[str] = None,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> list[Entity]: ...
+
+    # Fact CRUD
+    def add_fact(self, fact: Fact) -> Fact: ...
+    def get_facts(
+        self, entity_id: str, status: Optional[FactStatus] = None
+    ) -> list[Fact]: ...
+    def get_current_facts(self, entity_id: str) -> list[Fact]: ...
+    def update_fact(self, fact: Fact) -> Fact: ...
+
+    # Relations
+    def add_relation(self, relation: Relation) -> Relation: ...
+    def get_relations(
+        self, entity_id: str, direction: str = "both"
+    ) -> list[Relation]: ...
+
+    # Sessions
+    def save_session(self, session: Session) -> None: ...
+    def get_session(self, session_id: str) -> Optional[Session]: ...
+    def get_recent_sessions(
+        self, agent_id: str, limit: int = 5
+    ) -> list[Session]: ...
+    def add_session_event(self, event: SessionEvent) -> None: ...
+
+    # Conflicts
+    def add_conflict(self, conflict: dict) -> None: ...
+    def get_pending_conflicts(self) -> list[dict]: ...
+    def resolve_conflict(self, conflict_id: str, resolution: str, resolved_by: str) -> None: ...
+
+    # Stats
+    def entity_count(self) -> int: ...
+    def fact_count(self) -> int: ...

engram/storage/markdown_export.py

@@ -0,0 +1,144 @@
+"""Markdown exporter — one-way DB → Markdown for human readability."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from engram.models.entity import Entity
+from engram.models.fact import Fact
+from engram.models.relation import Relation
+
+
+def _slugify(name: str) -> str:
+    """Convert entity name to filesystem-safe slug."""
+    slug = name.lower().strip()
+    slug = re.sub(r'[^\w\s\u3040-\u9FFF\uAC00-\uD7AF-]', '', slug)
+    slug = re.sub(r'[\s_]+', '-', slug)
+    slug = slug.strip('-')
+    return slug[:80] if slug else "unnamed"
+
+
+class MarkdownExporter:
+    """One-way export: DB → Markdown files. Never reads from Markdown.
+
+    Generates human-readable Markdown files from structured DB data.
+    These files are for viewing only — the DB is the source of truth.
+    """
+
+    def __init__(self, export_dir: Path):
+        self.export_dir = Path(export_dir)
+        self.export_dir.mkdir(parents=True, exist_ok=True)
+
+    def export_entity(
+        self,
+        entity: Entity,
+        facts: list[Fact],
+        relations: list[Relation],
+    ) -> Path:
+        """Generate a Markdown file for a single entity."""
+        md = self._render_entity(entity, facts, relations)
+        filename = f"{_slugify(entity.name)}.md"
+        filepath = self.export_dir / filename
+        filepath.write_text(md, encoding="utf-8")
+        return filepath
+
+    def export_all(
+        self,
+        entities: list[tuple[Entity, list[Fact], list[Relation]]],
+    ) -> int:
+        """Export all entities. Returns count of files written."""
+        count = 0
+        for entity, facts, relations in entities:
+            self.export_entity(entity, facts, relations)
+            count += 1
+        return count
+
+    def _render_entity(
+        self,
+        entity: Entity,
+        facts: list[Fact],
+        relations: list[Relation],
+    ) -> str:
+        """Render entity data as Markdown."""
+        lines: list[str] = []
+
+        # Title
+        lines.append(f"# {entity.name}")
+        lines.append("")
+
+        # Summary
+        if entity.summary:
+            lines.append(f"> {entity.summary}")
+            lines.append("")
+
+        # State
+        state = entity.state.to_dict()
+        if state:
+            lines.append("## State")
+            for key, value in state.items():
+                if key == "custom" and isinstance(value, dict):
+                    for ck, cv in value.items():
+                        lines.append(f"- **{ck}**: {cv}")
+                else:
+                    lines.append(f"- **{key.title()}**: {value}")
+            lines.append("")
+
+        # Metadata
+        lines.append("## Metadata")
+        lines.append(f"- **Type**: {entity.entity_type}")
+        lines.append(f"- **Tier**: {entity.tier.value}")
+        lines.append(f"- **Updated**: {entity.updated_at.strftime('%Y-%m-%d %H:%M') if entity.updated_at else 'N/A'}")
+        if entity.aliases:
+            lines.append(f"- **Aliases**: {', '.join(entity.aliases)}")
+        lines.append("")
+
+        # Relations
+        if relations:
+            lines.append("## Relations")
+            for rel in relations:
+                if rel.from_entity_id == entity.id:
+                    lines.append(f"- {rel.relation_type} → `{rel.to_entity_id}`")
+                else:
+                    lines.append(f"- ← {rel.relation_type} from `{rel.from_entity_id}`")
+            lines.append("")
+
+        # Facts (current)
+        current_facts = [f for f in facts if f.is_current]
+        if current_facts:
+            lines.append("## Key Facts")
+            for fact in current_facts:
+                conf_label = self._confidence_label(fact.confidence)
+                source_info = f"{fact.source.type.value}"
+                if fact.source.author:
+                    source_info += f", {fact.source.author}"
+                lines.append(
+                    f"- {fact.raw_text} "
+                    f"[{conf_label}] "
+                    f"[Source: {source_info}]"
+                )
+            lines.append("")
+
+        # Timeline (all facts, chronological)
+        if facts:
+            lines.append("---")
+            lines.append("")
+            lines.append("## Timeline")
+            sorted_facts = sorted(facts, key=lambda f: f.created_at, reverse=True)
+            for fact in sorted_facts:
+                date_str = fact.created_at.strftime('%Y-%m-%d')
+                status_icon = "✓" if fact.is_current else "✗"
+                lines.append(f"- [{status_icon}] **{date_str}** | {fact.raw_text}")
+            lines.append("")
+
+        return "\n".join(lines)
+
+    def _confidence_label(self, confidence: float) -> str:
+        if confidence >= 0.8:
+            return "HIGH"
+        elif confidence >= 0.5:
+            return "MED"
+        elif confidence >= 0.3:
+            return "LOW"
+        else:
+            return "UNVERIFIED"

engram/storage/migrations.py

@@ -0,0 +1,30 @@
+"""Schema versioning and migration support."""
+
+from __future__ import annotations
+
+import sqlite3
+
+CURRENT_VERSION = 1
+
+
+def get_schema_version(conn: sqlite3.Connection) -> int:
+    try:
+        row = conn.execute("SELECT value FROM _meta WHERE key = 'schema_version'").fetchone()
+        return int(row[0]) if row else 0
+    except sqlite3.OperationalError:
+        return 0
+
+
+def migrate(conn: sqlite3.Connection) -> None:
+    """Run any pending migrations."""
+    version = get_schema_version(conn)
+    if version >= CURRENT_VERSION:
+        return
+    # Future migrations go here:
+    # if version < 2:
+    #     _migrate_v1_to_v2(conn)
+    conn.execute(
+        "INSERT OR REPLACE INTO _meta (key, value) VALUES (?, ?)",
+        ("schema_version", str(CURRENT_VERSION)),
+    )
+    conn.commit()