memanto 0.0.1__py3-none-any.whl

memanto/__init__.py

@@ -0,0 +1,3 @@
+"""
+MemAnto - Universal Memory Layer for Agentic AI
+"""

memanto/__main__.py

@@ -0,0 +1,8 @@
+"""
+MEMANTO - Main Entry Point
+"""
+
+from memanto.cli.main import app
+
+if __name__ == "__main__":
+    app()

memanto/app/__init__.py

@@ -0,0 +1,5 @@
+"""MEMANTO application package."""
+
+from ._version import __version__
+
+__all__ = ["__version__"]

memanto/app/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.0.1'
+__version_tuple__ = version_tuple = (0, 0, 1)
+
+__commit_id__ = commit_id = None

memanto/app/clients/moorcheh.py

@@ -0,0 +1,51 @@
+"""
+Moorcheh Client Singleton
+"""
+
+from moorcheh_sdk import AsyncMoorchehClient, MoorchehClient
+
+from memanto.app.config import settings
+
+
+class MoorchehClientSingleton:
+    """Singleton pattern for Moorcheh client"""
+
+    _instance = None
+    _client = None
+    _async_client = None
+
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def get_client(self) -> MoorchehClient:
+        """Get or create Moorcheh client"""
+        if self._client is None:
+            self._client = MoorchehClient(api_key=settings.MOORCHEH_API_KEY)
+        return self._client
+
+    def get_async_client(self) -> AsyncMoorchehClient:
+        """Get or create Async Moorcheh client"""
+        if self._async_client is None:
+            self._async_client = AsyncMoorchehClient(api_key=settings.MOORCHEH_API_KEY)
+        return self._async_client
+
+    def reset_client(self):
+        """Reset client (useful for testing)"""
+        self._client = None
+        self._async_client = None
+
+
+# Global client instance
+moorcheh_client = MoorchehClientSingleton()
+
+
+def get_moorcheh_client() -> MoorchehClient:
+    """Dependency injection function"""
+    return moorcheh_client.get_client()
+
+
+def get_async_moorcheh_client() -> AsyncMoorchehClient:
+    """Dependency injection function for async client"""
+    return moorcheh_client.get_async_client()

memanto/app/config.py

@@ -0,0 +1,100 @@
+"""
+MEMANTO Configuration
+
+Server-side settings (loaded from .env via pydantic-settings).
+CLI config models have been moved to cli/config/manager.py.
+"""
+
+from pathlib import Path
+
+from dotenv import load_dotenv
+from pydantic import BaseModel
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+# Load project .env first, then ~/.memanto/.env for the API key
+load_dotenv()
+_memanto_env = Path.home() / ".memanto" / ".env"
+if _memanto_env.exists():
+    load_dotenv(_memanto_env, override=True)
+
+
+# CLI & YAML Format Models (kept for backward compat with config.yaml structure)
+class ServerConfig(BaseModel):
+    """Server configuration"""
+
+    url: str = "localhost"
+    port: int = 8000
+    auto_start: bool = False
+
+
+class SessionConfig(BaseModel):
+    """Session management configuration"""
+
+    default_duration_hours: int = 6
+    auto_extend: bool = True
+    extend_threshold_minutes: int = 30
+    warn_before_expiry_minutes: int = 15
+    auto_renew_enabled: bool = True
+    auto_renew_interval_hours: int = 6
+
+
+class CLIConfig(BaseModel):
+    """CLI behavior configuration"""
+
+    interactive_mode: bool = True
+    smart_parse: bool = True
+    auto_title: bool = True
+    color_output: bool = True
+
+
+class Settings(BaseSettings):
+    """Unified Settings: sourced from environment / .env files"""
+
+    # Moorcheh Configuration
+    MOORCHEH_API_KEY: str = ""
+
+    # Server Configuration
+    HOST: str = "0.0.0.0"
+    PORT: int = 8000
+    DEBUG: bool = False
+
+    # CORS Configuration
+    ALLOWED_ORIGINS: list[str] = ["*"]
+
+    # Session Configuration
+    MEMANTO_SECRET_KEY: str = "memanto-default-secret-change-in-production"
+    SESSION_DEFAULT_DURATION_HOURS: int = 6
+    SESSION_AUTO_EXTEND: bool = True
+    SESSION_EXTEND_THRESHOLD_MINUTES: int = 30
+    SESSION_AUTO_RENEW_ENABLED: bool = True
+    SESSION_AUTO_RENEW_INTERVAL_HOURS: int = 6
+
+    # Memory Configuration
+    DEFAULT_TTL_SECONDS: int = 3600  # 1 hour
+    MAX_MEMORY_SIZE: int = 500  # characters
+    MAX_TITLE_SIZE: int = 100  # characters
+
+    # Answer Configuration
+    ANSWER_MODEL: str = "anthropic.claude-sonnet-4-6"
+    ANSWER_TEMPERATURE: float = 0.7
+    ANSWER_LIMIT: int = 15  # number of context memories to retrieve
+    ANSWER_THRESHOLD: float = 0.01  # confidence threshold for memory relevance
+
+    # Recall / Search Configuration
+    RECALL_LIMIT: int = 10  # default top-N results for recall/search
+
+    # Validation Configuration
+    REQUIRE_VALIDATION_FOR: list[str] = ["fact", "preference"]
+    PROVISIONAL_TTL_SECONDS: int = 3600  # 1 hour
+    PROVISIONAL_MAX_CONFIDENCE: float = 0.5
+
+    # Schedule Configuration
+    MEMANTO_SCHEDULE_TIME: str = "23:55"
+
+    model_config = SettingsConfigDict(
+        env_file=".env", case_sensitive=True, extra="ignore"
+    )
+
+
+# Global settings instance
+settings = Settings()

memanto/app/constants.py

@@ -0,0 +1,76 @@
+from typing import Literal
+
+# Memory Types
+MemoryType = Literal[
+    "fact",
+    "preference",
+    "goal",
+    "decision",
+    "artifact",
+    "learning",
+    "event",
+    "instruction",
+    "relationship",
+    "context",
+    "observation",
+    "commitment",
+    "error",
+]
+
+# Scope Types
+ScopeType = Literal["user", "workspace", "agent", "session", "project", "task"]
+
+# Source Types
+SourceType = str  # e.g., "user", "agent", "tool", "system", or specific "agent_name"
+
+# Status Types
+StatusType = Literal["active", "superseded", "deleted", "provisional"]
+
+# Provenance Types
+ProvenanceType = Literal[
+    "explicit_statement",
+    "inferred",
+    "corrected",
+    "validated",
+    "observed",
+    "imported",
+]
+
+# Validation Modes
+ValidationMode = Literal["strict", "lenient", "off"]
+
+# Actor Types
+ActorType = Literal["user", "agent", "system"]
+
+# Source Enumerations for Provenance
+ProvenanceSource = Literal["user", "agent", "tool", "system"]
+
+# Valid Lists for runtime checks
+VALID_MEMORY_TYPES = {
+    "fact",
+    "preference",
+    "goal",
+    "decision",
+    "artifact",
+    "learning",
+    "event",
+    "instruction",
+    "relationship",
+    "context",
+    "observation",
+    "commitment",
+    "error",
+}
+
+VALID_PROVENANCE_TYPES = {
+    "explicit_statement",
+    "inferred",
+    "corrected",
+    "validated",
+    "observed",
+    "imported",
+}
+
+VALID_SCOPE_TYPES = {"user", "workspace", "agent", "session", "project", "task"}
+
+VALID_PATTERNS = {"support", "project", "tool"}

memanto/app/core.py

@@ -0,0 +1,325 @@
+"""
+MEMANTO Core Architecture - Namespace Strategy & Memory Records
+"""
+
+import re
+import uuid
+from datetime import datetime, timedelta
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from memanto.app.constants import (
+    MemoryType,
+    ProvenanceType,
+    ScopeType,
+    SourceType,
+    StatusType,
+)
+
+
+class MemoryScope(BaseModel):
+    """Defines the scope for memory isolation"""
+
+    scope_type: ScopeType
+    scope_id: str
+
+    def to_namespace(self) -> str:
+        """Convert scope to Moorcheh namespace using deterministic mapping"""
+        # memanto_{scope_type}_{scope_id}
+        return f"memanto_{self.scope_type}_{self.scope_id}"
+
+    @classmethod
+    def from_namespace(cls, namespace: str) -> "MemoryScope":
+        """Parse namespace back to scope"""
+        from typing import cast
+
+        parts = namespace.split("_")
+        if len(parts) != 3 or parts[0] != "memanto":
+            raise ValueError(f"Invalid MEMANTO namespace format: {namespace}")
+        return cls(scope_type=cast(ScopeType, parts[1]), scope_id=parts[2])
+
+
+class MemoryRecord(BaseModel):
+    """Structured memory record with standardized format"""
+
+    # Core fields
+    id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    type: MemoryType
+    title: str = Field(max_length=100)
+    content: str = Field(max_length=10000)
+
+    # Metadata fields
+    scope_type: ScopeType
+    scope_id: str
+    actor_id: str
+    source: SourceType
+    source_ref: str | None = None
+    confidence: float = Field(ge=0.0, le=1.0, default=0.8)
+    status: StatusType = "active"
+    tags: list[str] = Field(default_factory=list)
+
+    # Provenance & Trust fields
+    provenance: ProvenanceType = "explicit_statement"
+    superseded_by: str | None = None  # Memory ID that supersedes this one
+    supersedes: str | None = None  # Memory ID that this supersedes
+    validated_at: datetime | None = None  # Last validation timestamp
+    validation_count: int = 0  # Number of times validated/confirmed
+    contradiction_detected: bool = False  # Flag for contradictions
+
+    # Timestamps (auto-populated by server)
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    updated_at: datetime = Field(default_factory=datetime.utcnow)
+    expires_at: datetime | None = None
+    ttl_seconds: int | None = None
+
+    def to_moorcheh_document(self) -> dict[str, Any]:
+        """
+        Convert to Moorcheh document format with flat metadata fields.
+
+        Moorcheh stores metadata as flat fields on the document, which enables
+        powerful filtering using the # syntax (e.g., #memory_type:fact #confidence>0.8)
+        """
+        # Format text as standardized card for semantic search
+        text = f"[{self.type.upper()}] {self.title}\n\n{self.content}"
+        if self.tags:
+            text += f"\n\nTags: {', '.join(self.tags)}"
+
+        # Build document with flat metadata fields (not nested!)
+        document = {
+            "id": self.id,
+            "text": text,
+            # Metadata fields (flat structure for Moorcheh filtering)
+            "memory_type": self.type,
+            "scope_type": self.scope_type,
+            "scope_id": self.scope_id,
+            "actor_id": self.actor_id,
+            "source": self.source,
+            "confidence": self.confidence,
+            "status": self.status,
+            # Provenance & Trust fields
+            "provenance": self.provenance,
+            "validation_count": self.validation_count,
+            "contradiction_detected": self.contradiction_detected,
+            # Timestamps
+            "created_at": self.created_at.isoformat(),
+            "updated_at": self.updated_at.isoformat(),
+        }
+
+        # Add optional fields only if present
+        if self.source_ref:
+            document["source_ref"] = self.source_ref
+        if self.tags:
+            document["tags"] = ",".join(self.tags)  # Comma-separated for filtering
+        if self.expires_at:
+            document["expires_at"] = self.expires_at.isoformat()
+        if self.ttl_seconds:
+            document["ttl_seconds"] = self.ttl_seconds
+        if self.superseded_by:
+            document["superseded_by"] = self.superseded_by
+        if self.supersedes:
+            document["supersedes"] = self.supersedes
+        if self.validated_at:
+            document["validated_at"] = self.validated_at.isoformat()
+
+        return document
+
+    def get_scope(self) -> MemoryScope:
+        """Get the memory scope"""
+        return MemoryScope(scope_type=self.scope_type, scope_id=self.scope_id)
+
+    def set_ttl(self, seconds: int):
+        """Set TTL and expiration"""
+        self.ttl_seconds = seconds
+        self.expires_at = datetime.utcnow() + timedelta(seconds=seconds)
+
+    def compute_confidence(self) -> float:
+        """
+        Compute confidence based on provenance, validation count, and age.
+
+        Returns adjusted confidence score considering:
+        - Provenance type (explicit > validated > observed > inferred)
+        - Validation count (more validations = higher confidence)
+        - Age decay for preferences (fresher = more trustworthy)
+        - Contradiction detection (contradicted = low confidence)
+        """
+        if self.contradiction_detected:
+            return max(
+                0.1, self.confidence * 0.3
+            )  # Contradicted memories get very low confidence
+
+        if self.status == "superseded":
+            return 0.0  # Superseded memories have zero confidence
+
+        # Base confidence from provenance
+        provenance_weights = {
+            "explicit_statement": 1.0,
+            "validated": 0.95,
+            "observed": 0.85,
+            "corrected": 0.9,
+            "inferred": 0.7,
+            "imported": 0.8,
+        }
+        base = self.confidence * provenance_weights.get(self.provenance, 0.8)
+
+        # Validation boost (each validation adds confidence)
+        validation_boost = min(0.15, self.validation_count * 0.03)
+
+        # Age decay for preferences and observations (fresher = more trustworthy)
+        if self.type in ["preference", "observation"]:
+            age_days = (datetime.utcnow() - self.created_at).days
+            if age_days > 90:  # 3 months
+                age_penalty = 0.2
+            elif age_days > 30:  # 1 month
+                age_penalty = 0.1
+            else:
+                age_penalty = 0.0
+        else:
+            age_penalty = 0.0
+
+        # Compute final confidence
+        final = min(1.0, base + validation_boost - age_penalty)
+        return round(final, 2)
+
+    def validate(self):
+        """Mark memory as validated (increases trust)"""
+        self.validation_count += 1
+        self.validated_at = datetime.utcnow()
+        self.updated_at = datetime.utcnow()
+
+        # Upgrade provenance if inferred
+        if self.provenance == "inferred":
+            self.provenance = "validated"
+
+    def mark_superseded(self, superseded_by_id: str):
+        """Mark this memory as superseded by a newer one"""
+        self.superseded_by = superseded_by_id
+        self.status = "superseded"
+        self.updated_at = datetime.utcnow()
+
+    def detect_contradiction(self):
+        """Flag memory as contradicted (lowers trust)"""
+        self.contradiction_detected = True
+        self.updated_at = datetime.utcnow()
+
+    def trust_score(self) -> dict[str, Any]:
+        """
+        Calculate comprehensive trust score with explanation.
+
+        Returns dict with:
+        - computed_confidence: float
+        - provenance: str
+        - validation_count: int
+        - age_days: int
+        - is_superseded: bool
+        - contradiction_detected: bool
+        - trust_level: str (high/medium/low)
+        - recommendation: str
+        """
+        computed_conf = self.compute_confidence()
+        age_days = (datetime.utcnow() - self.created_at).days
+
+        # Determine trust level
+        if computed_conf >= 0.8 and not self.contradiction_detected:
+            trust_level = "high"
+            recommendation = "Safe to use"
+        elif computed_conf >= 0.5:
+            trust_level = "medium"
+            recommendation = "Use with caution"
+        else:
+            trust_level = "low"
+            recommendation = "Verify before using"
+
+        return {
+            "computed_confidence": computed_conf,
+            "original_confidence": self.confidence,
+            "provenance": self.provenance,
+            "validation_count": self.validation_count,
+            "age_days": age_days,
+            "is_superseded": self.status == "superseded",
+            "contradiction_detected": self.contradiction_detected,
+            "trust_level": trust_level,
+            "recommendation": recommendation,
+            "last_validated": self.validated_at.isoformat()
+            if self.validated_at
+            else None,
+        }
+
+
+class ValidationPolicy:
+    """Memory validation policy to prevent poisoning"""
+
+    @staticmethod
+    def validate_memory(
+        memory: MemoryRecord, context: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        """
+        Validate memory before storage
+        Returns: {"valid": bool, "action": str, "reason": str}
+        """
+        context = context or {}
+
+        # High-confidence types require validation
+        if memory.type in ["fact", "preference"]:
+            return ValidationPolicy._validate_critical_memory(memory, context)
+
+        # Other types are generally safe
+        return {"valid": True, "action": "store", "reason": "Non-critical memory type"}
+
+    @staticmethod
+    def _validate_critical_memory(
+        memory: MemoryRecord, context: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Validate critical memory types (fact, preference)"""
+
+        # Check for explicit user confirmation
+        if context.get("user_confirmed"):
+            return {"valid": True, "action": "store", "reason": "User confirmed"}
+
+        # Check for repetition (same content seen before)
+        if context.get("repetition_count", 0) >= 2:
+            return {"valid": True, "action": "store", "reason": "Repeated content"}
+
+        # Check for tool-grounded source
+        if memory.source == "tool" and memory.source_ref:
+            return {"valid": True, "action": "store", "reason": "Tool-grounded"}
+
+        # Check for high confidence from reliable source
+        if memory.confidence >= 0.9 and memory.source in ["system", "tool"]:
+            return {
+                "valid": True,
+                "action": "store",
+                "reason": "High confidence system source",
+            }
+
+        # Default: store as provisional
+        return {
+            "valid": True,
+            "action": "store_provisional",
+            "reason": "Requires validation - storing as provisional",
+        }
+
+    @staticmethod
+    def make_provisional(memory: MemoryRecord) -> MemoryRecord:
+        """Convert memory to provisional status with short TTL"""
+        memory.status = "provisional"
+        memory.confidence = min(memory.confidence, 0.5)  # Cap confidence
+        memory.set_ttl(3600)  # 1 hour TTL
+        return memory
+
+
+# Utility functions
+def create_memory_scope(scope_type: ScopeType, scope_id: str) -> MemoryScope:
+    """Helper to create memory scope"""
+    return MemoryScope(scope_type=scope_type, scope_id=scope_id)
+
+
+def parse_namespace(namespace: str) -> MemoryScope:
+    """Helper to parse namespace"""
+    return MemoryScope.from_namespace(namespace)
+
+
+def validate_namespace_format(namespace: str) -> bool:
+    """Validate namespace follows MEMANTO convention"""
+    pattern = r"^memanto_(user|workspace|agent|session)_[a-zA-Z0-9_-]+$"
+    return bool(re.match(pattern, namespace))

memanto/app/main.py

@@ -0,0 +1,66 @@
+"""
+MEMANTO FastAPI Application
+"""
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from memanto.app import __version__
+from memanto.app.config import settings
+from memanto.app.routes import context, health, memory, namespaces, sessions
+from memanto.app.ui.routes.ui_router import mount_ui_static
+from memanto.app.ui.routes.ui_router import router as ui_router
+
+# Create FastAPI app
+app = FastAPI(
+    title="MemAnto - Universal Memory Layer for Agentic AI",
+    description="A memory layer service for agentic AI systems using Moorcheh SDK",
+    version=__version__,
+    docs_url="/docs",
+    redoc_url="/redoc",
+)
+
+# Add CORS middleware
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.ALLOWED_ORIGINS,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Include routers
+app.include_router(health.router, tags=["Health"])
+
+# Session-Based API (Primary)
+app.include_router(sessions.router, prefix="/api/v2", tags=["Sessions & Agents"])
+
+
+# Internal/Advanced APIs
+app.include_router(
+    namespaces.router, prefix="/api/v1/namespaces", tags=["Namespaces (Internal)"]
+)
+app.include_router(memory.router, prefix="/api/v1/memory", tags=["Memory (Internal)"])
+app.include_router(
+    context.router, prefix="/api/v1/context", tags=["Context (Internal)"]
+)
+
+# Web UI Dashboard
+app.include_router(ui_router, tags=["Web UI"])
+mount_ui_static(app)
+
+
+@app.get("/")
+async def root():
+    return {
+        "service": "MEMANTO",
+        "description": "Universal Memory Layer for Agentic AI",
+        "version": __version__,
+        "docs": "/docs",
+    }
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run(app, host="0.0.0.0", port=8000)