neural-memory 0.1.0__py3-none-any.whl

neural_memory/safety/freshness.py

@@ -0,0 +1,238 @@
+"""Memory freshness evaluation for Neural Memory.
+
+Evaluates how fresh/stale memories are and provides warnings
+for potentially outdated information.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from enum import StrEnum
+
+
+class FreshnessLevel(StrEnum):
+    """Freshness levels for memories."""
+
+    FRESH = "fresh"  # < 7 days
+    RECENT = "recent"  # 7-30 days
+    AGING = "aging"  # 30-90 days
+    STALE = "stale"  # 90-365 days
+    ANCIENT = "ancient"  # > 365 days
+
+
+@dataclass
+class FreshnessResult:
+    """Result of freshness evaluation."""
+
+    level: FreshnessLevel
+    age_days: int
+    warning: str | None
+    should_verify: bool
+    score: float  # 0.0 (ancient) to 1.0 (fresh)
+
+
+# Default thresholds in days
+DEFAULT_THRESHOLDS = {
+    FreshnessLevel.FRESH: 7,
+    FreshnessLevel.RECENT: 30,
+    FreshnessLevel.AGING: 90,
+    FreshnessLevel.STALE: 365,
+}
+
+
+def evaluate_freshness(
+    created_at: datetime,
+    reference_time: datetime | None = None,
+    thresholds: dict[FreshnessLevel, int] | None = None,
+) -> FreshnessResult:
+    """
+    Evaluate the freshness of a memory.
+
+    Args:
+        created_at: When the memory was created
+        reference_time: Reference time for comparison (default: now)
+        thresholds: Custom thresholds in days
+
+    Returns:
+        FreshnessResult with level, warning, and score
+    """
+    if reference_time is None:
+        reference_time = datetime.now()
+
+    if thresholds is None:
+        thresholds = DEFAULT_THRESHOLDS
+
+    # Calculate age
+    age = reference_time - created_at
+    age_days = max(0, age.days)
+
+    # Determine level
+    if age_days < thresholds[FreshnessLevel.FRESH]:
+        level = FreshnessLevel.FRESH
+        score = 1.0
+        warning = None
+        should_verify = False
+    elif age_days < thresholds[FreshnessLevel.RECENT]:
+        level = FreshnessLevel.RECENT
+        score = 0.8
+        warning = None
+        should_verify = False
+    elif age_days < thresholds[FreshnessLevel.AGING]:
+        level = FreshnessLevel.AGING
+        score = 0.5
+        warning = f"[~] This memory is {age_days} days old - information may have changed"
+        should_verify = True
+    elif age_days < thresholds[FreshnessLevel.STALE]:
+        level = FreshnessLevel.STALE
+        score = 0.3
+        warning = f"[!] STALE: This memory is {age_days} days old - verify before using"
+        should_verify = True
+    else:
+        level = FreshnessLevel.ANCIENT
+        score = 0.1
+        warning = f"[!!] ANCIENT: This memory is {age_days} days old ({age_days // 365} years) - likely outdated"
+        should_verify = True
+
+    return FreshnessResult(
+        level=level,
+        age_days=age_days,
+        warning=warning,
+        should_verify=should_verify,
+        score=score,
+    )
+
+
+def get_freshness_warning(
+    created_at: datetime,
+    reference_time: datetime | None = None,
+) -> str | None:
+    """
+    Get a warning message if memory is stale.
+
+    Args:
+        created_at: When the memory was created
+        reference_time: Reference time for comparison
+
+    Returns:
+        Warning message or None if fresh
+    """
+    result = evaluate_freshness(created_at, reference_time)
+    return result.warning
+
+
+def format_age(age_days: int) -> str:
+    """Format age in human-readable form."""
+    if age_days == 0:
+        return "today"
+    elif age_days == 1:
+        return "yesterday"
+    elif age_days < 7:
+        return f"{age_days} days ago"
+    elif age_days < 30:
+        weeks = age_days // 7
+        return f"{weeks} week{'s' if weeks > 1 else ''} ago"
+    elif age_days < 365:
+        months = age_days // 30
+        return f"{months} month{'s' if months > 1 else ''} ago"
+    else:
+        years = age_days // 365
+        return f"{years} year{'s' if years > 1 else ''} ago"
+
+
+def get_freshness_indicator(level: FreshnessLevel, use_ascii: bool = True) -> str:
+    """Get a visual indicator for freshness level.
+
+    Args:
+        level: Freshness level
+        use_ascii: Use ASCII characters instead of emojis (for Windows compatibility)
+    """
+    if use_ascii:
+        indicators = {
+            FreshnessLevel.FRESH: "[+]",
+            FreshnessLevel.RECENT: "[+]",
+            FreshnessLevel.AGING: "[~]",
+            FreshnessLevel.STALE: "[!]",
+            FreshnessLevel.ANCIENT: "[!!]",
+        }
+    else:
+        indicators = {
+            FreshnessLevel.FRESH: "G",
+            FreshnessLevel.RECENT: "G",
+            FreshnessLevel.AGING: "Y",
+            FreshnessLevel.STALE: "O",
+            FreshnessLevel.ANCIENT: "R",
+        }
+    return indicators.get(level, "[ ]")
+
+
+@dataclass
+class MemoryFreshnessReport:
+    """Report on memory freshness for a set of memories."""
+
+    total: int
+    fresh: int
+    recent: int
+    aging: int
+    stale: int
+    ancient: int
+    average_age_days: float
+    oldest_days: int
+    newest_days: int
+
+    def summary(self) -> str:
+        """Get a summary string."""
+        lines = [
+            f"Total memories: {self.total}",
+            f"  🟢 Fresh (<7d): {self.fresh}",
+            f"  🟢 Recent (7-30d): {self.recent}",
+            f"  🟡 Aging (30-90d): {self.aging}",
+            f"  🟠 Stale (90-365d): {self.stale}",
+            f"  🔴 Ancient (>365d): {self.ancient}",
+            f"Average age: {self.average_age_days:.1f} days",
+        ]
+        return "\n".join(lines)
+
+
+def analyze_freshness(
+    created_dates: list[datetime],
+    reference_time: datetime | None = None,
+) -> MemoryFreshnessReport:
+    """
+    Analyze freshness of a collection of memories.
+
+    Args:
+        created_dates: List of creation timestamps
+        reference_time: Reference time for comparison
+
+    Returns:
+        MemoryFreshnessReport with statistics
+    """
+    if not created_dates:
+        return MemoryFreshnessReport(
+            total=0,
+            fresh=0,
+            recent=0,
+            aging=0,
+            stale=0,
+            ancient=0,
+            average_age_days=0,
+            oldest_days=0,
+            newest_days=0,
+        )
+
+    results = [evaluate_freshness(dt, reference_time) for dt in created_dates]
+
+    ages = [r.age_days for r in results]
+
+    return MemoryFreshnessReport(
+        total=len(results),
+        fresh=sum(1 for r in results if r.level == FreshnessLevel.FRESH),
+        recent=sum(1 for r in results if r.level == FreshnessLevel.RECENT),
+        aging=sum(1 for r in results if r.level == FreshnessLevel.AGING),
+        stale=sum(1 for r in results if r.level == FreshnessLevel.STALE),
+        ancient=sum(1 for r in results if r.level == FreshnessLevel.ANCIENT),
+        average_age_days=sum(ages) / len(ages),
+        oldest_days=max(ages),
+        newest_days=min(ages),
+    )

neural_memory/safety/sensitive.py

@@ -0,0 +1,304 @@
+"""Sensitive content detection for Neural Memory.
+
+Detects potentially sensitive information like:
+- API keys and secrets
+- Passwords and tokens
+- Personal identifiable information (PII)
+- Credit card numbers
+- Private keys
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from enum import StrEnum
+
+
+class SensitiveType(StrEnum):
+    """Types of sensitive content."""
+
+    API_KEY = "api_key"
+    PASSWORD = "password"
+    SECRET = "secret"
+    TOKEN = "token"
+    PRIVATE_KEY = "private_key"
+    CREDIT_CARD = "credit_card"
+    SSN = "ssn"
+    EMAIL = "email"
+    PHONE = "phone"
+    AWS_KEY = "aws_key"
+    DATABASE_URL = "database_url"
+    JWT = "jwt"
+    GENERIC_SECRET = "generic_secret"
+
+
+@dataclass(frozen=True)
+class SensitivePattern:
+    """A pattern for detecting sensitive content."""
+
+    name: str
+    pattern: str
+    type: SensitiveType
+    description: str
+    severity: int = 1  # 1=low, 2=medium, 3=high
+
+
+@dataclass
+class SensitiveMatch:
+    """A match found in content."""
+
+    pattern_name: str
+    matched_text: str
+    type: SensitiveType
+    severity: int
+    start: int
+    end: int
+
+    def redacted(self) -> str:
+        """Get redacted version of matched text."""
+        if len(self.matched_text) <= 8:
+            return "*" * len(self.matched_text)
+        return self.matched_text[:4] + "*" * (len(self.matched_text) - 8) + self.matched_text[-4:]
+
+
+def get_default_patterns() -> list[SensitivePattern]:
+    """Get default sensitive content patterns."""
+    return [
+        # API Keys and Secrets
+        SensitivePattern(
+            name="Generic API Key",
+            pattern=r"(?i)(api[_-]?key|apikey)\s*[=:]\s*['\"]?([a-zA-Z0-9_\-]{16,})['\"]?",
+            type=SensitiveType.API_KEY,
+            description="Generic API key assignment",
+            severity=3,
+        ),
+        SensitivePattern(
+            name="Generic Secret",
+            pattern=r"(?i)(secret|secret[_-]?key)\s*[=:]\s*['\"]?([a-zA-Z0-9_\-]{16,})['\"]?",
+            type=SensitiveType.SECRET,
+            description="Generic secret assignment",
+            severity=3,
+        ),
+        SensitivePattern(
+            name="Generic Password",
+            pattern=r"(?i)(password|passwd|pwd)\s*[=:]\s*['\"]?([^\s'\"]{4,})['\"]?",
+            type=SensitiveType.PASSWORD,
+            description="Password assignment",
+            severity=3,
+        ),
+        SensitivePattern(
+            name="Generic Token",
+            pattern=r"(?i)(token|auth[_-]?token|access[_-]?token|bearer)\s*[=:]\s*['\"]?([a-zA-Z0-9_\-\.]{16,})['\"]?",
+            type=SensitiveType.TOKEN,
+            description="Auth token assignment",
+            severity=3,
+        ),
+        # AWS
+        SensitivePattern(
+            name="AWS Access Key",
+            pattern=r"(?i)aws[_-]?access[_-]?key[_-]?id\s*[=:]\s*['\"]?(AKIA[0-9A-Z]{16})['\"]?",
+            type=SensitiveType.AWS_KEY,
+            description="AWS Access Key ID",
+            severity=3,
+        ),
+        SensitivePattern(
+            name="AWS Secret Key",
+            pattern=r"(?i)aws[_-]?secret[_-]?access[_-]?key\s*[=:]\s*['\"]?([a-zA-Z0-9/+=]{40})['\"]?",
+            type=SensitiveType.AWS_KEY,
+            description="AWS Secret Access Key",
+            severity=3,
+        ),
+        # Database
+        SensitivePattern(
+            name="Database URL",
+            pattern=r"(?i)(postgres|mysql|mongodb|redis)://[^\s]+:[^\s]+@[^\s]+",
+            type=SensitiveType.DATABASE_URL,
+            description="Database connection string with credentials",
+            severity=3,
+        ),
+        # Private Keys
+        SensitivePattern(
+            name="Private Key",
+            pattern=r"-----BEGIN\s+(RSA|DSA|EC|OPENSSH|PGP)?\s*PRIVATE KEY-----",
+            type=SensitiveType.PRIVATE_KEY,
+            description="Private key header",
+            severity=3,
+        ),
+        # JWT
+        SensitivePattern(
+            name="JWT Token",
+            pattern=r"eyJ[a-zA-Z0-9_-]*\.eyJ[a-zA-Z0-9_-]*\.[a-zA-Z0-9_-]*",
+            type=SensitiveType.JWT,
+            description="JSON Web Token",
+            severity=2,
+        ),
+        # Credit Card (basic pattern)
+        SensitivePattern(
+            name="Credit Card",
+            pattern=r"\b(?:4[0-9]{12}(?:[0-9]{3})?|5[1-5][0-9]{14}|3[47][0-9]{13}|6(?:011|5[0-9]{2})[0-9]{12})\b",
+            type=SensitiveType.CREDIT_CARD,
+            description="Credit card number",
+            severity=3,
+        ),
+        # SSN (US)
+        SensitivePattern(
+            name="SSN",
+            pattern=r"\b\d{3}-\d{2}-\d{4}\b",
+            type=SensitiveType.SSN,
+            description="Social Security Number format",
+            severity=3,
+        ),
+        # Long random strings (potential secrets)
+        SensitivePattern(
+            name="Long Base64 String",
+            pattern=r"\b[A-Za-z0-9+/]{40,}={0,2}\b",
+            type=SensitiveType.GENERIC_SECRET,
+            description="Long base64-encoded string (potential secret)",
+            severity=1,
+        ),
+        # Hex strings (potential keys)
+        SensitivePattern(
+            name="Long Hex String",
+            pattern=r"\b[a-fA-F0-9]{32,}\b",
+            type=SensitiveType.GENERIC_SECRET,
+            description="Long hexadecimal string (potential key)",
+            severity=1,
+        ),
+    ]
+
+
+def check_sensitive_content(
+    content: str,
+    patterns: list[SensitivePattern] | None = None,
+    min_severity: int = 1,
+) -> list[SensitiveMatch]:
+    """
+    Check content for sensitive information.
+
+    Args:
+        content: Text to check
+        patterns: Patterns to use (default: get_default_patterns())
+        min_severity: Minimum severity level to report (1-3)
+
+    Returns:
+        List of sensitive matches found
+    """
+    if patterns is None:
+        patterns = get_default_patterns()
+
+    matches: list[SensitiveMatch] = []
+
+    for pattern in patterns:
+        if pattern.severity < min_severity:
+            continue
+
+        try:
+            regex = re.compile(pattern.pattern)
+            for match in regex.finditer(content):
+                matches.append(
+                    SensitiveMatch(
+                        pattern_name=pattern.name,
+                        matched_text=match.group(0),
+                        type=pattern.type,
+                        severity=pattern.severity,
+                        start=match.start(),
+                        end=match.end(),
+                    )
+                )
+        except re.error:
+            # Skip invalid patterns
+            continue
+
+    # Remove duplicates (same position)
+    seen_positions: set[tuple[int, int]] = set()
+    unique_matches: list[SensitiveMatch] = []
+    for match in matches:
+        pos = (match.start, match.end)
+        if pos not in seen_positions:
+            seen_positions.add(pos)
+            unique_matches.append(match)
+
+    return sorted(unique_matches, key=lambda m: (-m.severity, m.start))
+
+
+def filter_sensitive_content(
+    content: str,
+    patterns: list[SensitivePattern] | None = None,
+    replacement: str = "[REDACTED]",
+) -> tuple[str, list[SensitiveMatch]]:
+    """
+    Filter sensitive content by replacing matches.
+
+    Args:
+        content: Text to filter
+        patterns: Patterns to use
+        replacement: Replacement text
+
+    Returns:
+        Tuple of (filtered_content, matches_found)
+    """
+    matches = check_sensitive_content(content, patterns)
+
+    if not matches:
+        return content, []
+
+    # Sort by position descending to replace from end
+    sorted_matches = sorted(matches, key=lambda m: m.start, reverse=True)
+
+    filtered = content
+    for match in sorted_matches:
+        filtered = filtered[: match.start] + replacement + filtered[match.end :]
+
+    return filtered, matches
+
+
+def format_sensitive_warning(matches: list[SensitiveMatch], use_ascii: bool = False) -> str:
+    """Format a warning message for sensitive content.
+
+    Args:
+        matches: List of sensitive matches
+        use_ascii: Use ASCII characters instead of emojis (for Windows compatibility)
+    """
+    if not matches:
+        return ""
+
+    # Use ASCII or Unicode based on preference/platform
+    if use_ascii:
+        warn_icon = "[!]"
+        high_icon = "[!!!]"
+        medium_icon = "[!!]"
+        low_icon = "[!]"
+    else:
+        warn_icon = "<!>"
+        high_icon = "[HIGH]"
+        medium_icon = "[MED]"
+        low_icon = "[LOW]"
+
+    lines = [f"{warn_icon} SENSITIVE CONTENT DETECTED:"]
+
+    # Group by severity
+    high = [m for m in matches if m.severity == 3]
+    medium = [m for m in matches if m.severity == 2]
+    low = [m for m in matches if m.severity == 1]
+
+    if high:
+        lines.append(f"\n  {high_icon} HIGH RISK:")
+        for m in high:
+            lines.append(f"     - {m.pattern_name}: {m.redacted()}")
+
+    if medium:
+        lines.append(f"\n  {medium_icon} MEDIUM RISK:")
+        for m in medium:
+            lines.append(f"     - {m.pattern_name}: {m.redacted()}")
+
+    if low:
+        lines.append(f"\n  {low_icon} LOW RISK:")
+        for m in low[:3]:  # Limit low risk to 3
+            lines.append(f"     - {m.pattern_name}")
+        if len(low) > 3:
+            lines.append(f"     ... and {len(low) - 3} more")
+
+    lines.append("\n  Use --force to store anyway, or --redact to auto-redact.")
+
+    return "\n".join(lines)

neural_memory/server/__init__.py

@@ -0,0 +1,5 @@
+"""FastAPI server for NeuralMemory."""
+
+from neural_memory.server.app import create_app
+
+__all__ = ["create_app"]

neural_memory/server/app.py

@@ -0,0 +1,99 @@
+"""FastAPI application factory."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from neural_memory import __version__
+from neural_memory.server.models import HealthResponse
+from neural_memory.server.routes import brain_router, memory_router, sync_router
+from neural_memory.storage.memory_store import InMemoryStorage
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
+    """Application lifespan handler."""
+    # Startup
+    app.state.storage = InMemoryStorage()
+    yield
+    # Shutdown
+    pass
+
+
+def create_app(
+    title: str = "NeuralMemory",
+    description: str = "Reflex-based memory system for AI agents",
+    cors_origins: list[str] | None = None,
+) -> FastAPI:
+    """
+    Create and configure the FastAPI application.
+
+    Args:
+        title: API title
+        description: API description
+        cors_origins: Allowed CORS origins (default: ["*"])
+
+    Returns:
+        Configured FastAPI application
+    """
+    app = FastAPI(
+        title=title,
+        description=description,
+        version=__version__,
+        lifespan=lifespan,
+        docs_url="/docs",
+        redoc_url="/redoc",
+    )
+
+    # CORS middleware
+    if cors_origins is None:
+        cors_origins = ["*"]
+
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=cors_origins,
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    # Override storage dependency using the shared module
+    from neural_memory.server.dependencies import get_storage as shared_get_storage
+
+    async def get_storage() -> InMemoryStorage:
+        return app.state.storage
+
+    app.dependency_overrides[shared_get_storage] = get_storage
+
+    # Include routers
+    app.include_router(memory_router)
+    app.include_router(brain_router)
+    app.include_router(sync_router)
+
+    # Health check endpoint
+    @app.get("/health", response_model=HealthResponse, tags=["health"])
+    async def health_check() -> HealthResponse:
+        """Health check endpoint."""
+        return HealthResponse(status="healthy", version=__version__)
+
+    # Root endpoint
+    @app.get("/", tags=["health"])
+    async def root() -> dict:
+        """Root endpoint with API info."""
+        return {
+            "name": title,
+            "description": description,
+            "version": __version__,
+            "docs": "/docs",
+            "health": "/health",
+        }
+
+    return app
+
+
+# Create default app instance for uvicorn
+app = create_app()

neural_memory/server/dependencies.py

@@ -0,0 +1,33 @@
+"""Shared dependencies for API routes."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import Depends, Header, HTTPException
+
+from neural_memory.core.brain import Brain
+from neural_memory.storage.base import NeuralStorage
+
+
+async def get_storage() -> NeuralStorage:
+    """
+    Dependency to get storage instance.
+
+    This is overridden by the application at startup.
+    """
+    raise NotImplementedError("Storage not configured")
+
+
+async def get_brain(
+    brain_id: Annotated[str, Header(alias="X-Brain-ID")],
+    storage: Annotated[NeuralStorage, Depends(get_storage)],
+) -> Brain:
+    """Dependency to get and validate brain from header."""
+    brain = await storage.get_brain(brain_id)
+    if brain is None:
+        raise HTTPException(status_code=404, detail=f"Brain {brain_id} not found")
+
+    # Set brain context
+    storage.set_brain(brain_id)  # type: ignore
+    return brain