memlint 0.1.0__py3-none-any.whl

memlint/__init__.py

@@ -0,0 +1,19 @@
+from memlint.core import StaleDetector
+from memlint.models import (
+    MemoryFact,
+    StalenessResult,
+    DetectionReport,
+    FactCategory,
+    StalenessLevel,
+)
+from memlint.classifier import classify_fact_async
+
+__all__ = [
+    "StaleDetector",
+    "MemoryFact",
+    "StalenessResult",
+    "DetectionReport",
+    "FactCategory",
+    "StalenessLevel",
+    "classify_fact_async",
+]

memlint/adapters/_utils.py

@@ -0,0 +1,8 @@
+from datetime import datetime
+from dateutil import parser as dateutil_parser
+
+
+def parse_dt(value: str | None) -> datetime | None:
+    if value is None:
+        return None
+    return dateutil_parser.parse(value).replace(tzinfo=None)

memlint/adapters/json_adapter.py

@@ -0,0 +1,28 @@
+import json
+from memlint.adapters._utils import parse_dt
+from memlint.models import MemoryFact
+
+
+def load_from_json(filepath: str) -> list[MemoryFact]:
+    with open(filepath, "r", encoding="utf-8") as f:
+        data = json.load(f)
+
+    if not isinstance(data, list):
+        raise ValueError(f"Expected a JSON array at root, got {type(data).__name__}")
+
+    facts = []
+    for i, entry in enumerate(data):
+        for required in ("id", "content", "created_at"):
+            if required not in entry:
+                raise ValueError(f"Entry {i} missing required field '{required}'")
+
+        facts.append(MemoryFact(
+            id=entry["id"],
+            content=entry["content"],
+            created_at=parse_dt(entry["created_at"]),
+            last_confirmed_at=parse_dt(entry.get("last_confirmed_at")),
+            confirmation_count=entry.get("confirmation_count", 0),
+            source=entry.get("source", "user"),
+            metadata=entry.get("metadata", {}),
+        ))
+    return facts

memlint/adapters/langchain_tool.py

@@ -0,0 +1,25 @@
+import json
+from memlint.models import MemoryFact
+
+try:
+    from langchain_core.tools import tool
+    LANGCHAIN_AVAILABLE = True
+except ImportError:
+    LANGCHAIN_AVAILABLE = False
+
+if LANGCHAIN_AVAILABLE:
+    from memlint.core import StaleDetector
+
+    @tool
+    def check_memory_staleness(fact_json: str) -> str:
+        """Check if a single memory fact is stale before injecting it into context."""
+        fact = MemoryFact.model_validate(json.loads(fact_json))
+        result = StaleDetector().check_one(fact)
+        return result.model_dump_json()
+
+    @tool
+    def filter_stale_memories(facts_json: str) -> str:
+        """Filter out stale and expired memory facts from a list, returning only safe-to-use facts."""
+        facts = [MemoryFact.model_validate(d) for d in json.loads(facts_json)]
+        safe = StaleDetector().filter_safe(facts)
+        return json.dumps([f.model_dump() for f in safe], default=str)

memlint/adapters/mem0_adapter.py

@@ -0,0 +1,28 @@
+import json
+from memlint.adapters._utils import parse_dt
+from memlint.models import MemoryFact
+
+
+def load_from_mem0(filepath: str) -> list[MemoryFact]:
+    with open(filepath, "r", encoding="utf-8") as f:
+        data = json.load(f)
+
+    if not isinstance(data, list):
+        raise ValueError(f"Expected a JSON array at root, got {type(data).__name__}")
+
+    facts = []
+    for i, entry in enumerate(data):
+        for required in ("id", "memory", "created_at"):
+            if required not in entry:
+                raise ValueError(f"Entry {i} missing required field '{required}'")
+
+        facts.append(MemoryFact(
+            id=entry["id"],
+            content=entry["memory"],
+            created_at=parse_dt(entry["created_at"]),
+            last_confirmed_at=parse_dt(entry.get("updated_at")),
+            confirmation_count=entry.get("confirmation_count", 0),
+            source=entry.get("source", "user"),
+            metadata=entry.get("metadata", {}),
+        ))
+    return facts

memlint/classifier.py

@@ -0,0 +1,155 @@
+from memlint.models import FactCategory
+
+CATEGORY_KEYWORDS: dict[FactCategory, list[str]] = {
+    FactCategory.LOCATION: [
+        "lives", "located", "based in", "address", "city", "country",
+        "office", "moved to", "residing", "hometown", "location",
+    ],
+    FactCategory.EMPLOYMENT: [
+        "works at", "employed", "job", "role", "position", "company",
+        "organization", "joined", "hired", "manager", "team", "department",
+        "title", "consultant", "engineer", "analyst", "intern",
+    ],
+    FactCategory.PROJECT: [
+        "project", "building", "repo", "codebase", "app", "tool",
+        "working on", "developing", "implementing", "stack", "framework",
+        "library", "version", "api", "endpoint", "deployed", "launched",
+    ],
+    FactCategory.PREFERENCE: [
+        "prefers", "likes", "favorite", "enjoys", "uses", "dislikes",
+        "wants", "chooses", "opts for", "theme", "mode", "setting",
+        "style", "approach",
+    ],
+    FactCategory.RELATIONSHIP: [
+        "friend", "colleague", "manager", "reports to", "partner",
+        "teammate", "mentor", "client", "collaborator", "family",
+    ],
+    FactCategory.IDENTITY: [
+        "name is", "called", "age", "born", "nationality", "speaks",
+        "gender", "education", "degree", "graduated", "alumni",
+    ],
+    FactCategory.EPISODIC: [
+        "today", "yesterday", "last week", "this morning", "just",
+        "recently", "earlier", "said that", "mentioned", "asked about",
+        "discussed", "fixed", "resolved", "debugging",
+    ],
+    FactCategory.SYSTEM_FACT: [
+        "python version", "node version", "npm", "pip", "docker",
+        "os", "operating system", "machine", "cpu", "ram", "disk",
+        "installed", "configured", "environment", "env", ".env",
+    ],
+}
+
+CLASSIFY_PROMPT = """You are classifying a memory fact into exactly one category.
+
+Categories:
+- location: where someone lives, works, or is based
+- employment: job, company, role, title, team
+- project: software projects, tools being built, tech stack
+- preference: likes, dislikes, habits, settings
+- relationship: people the user knows or works with
+- identity: name, age, education, nationality, languages spoken
+- episodic: time-specific events, recent actions, things that happened
+- system_fact: software versions, OS, environment config
+- unknown: does not fit any category
+
+Memory fact: "{fact}"
+
+Respond with ONLY the category name, nothing else. Example: "employment"
+"""
+
+
+def _rule_based_classify(content: str) -> FactCategory:
+    lower = content.lower()
+    scores: dict[FactCategory, int] = {}
+    for category, keywords in CATEGORY_KEYWORDS.items():
+        hits = sum(1 for kw in keywords if kw in lower)
+        if hits > 0:
+            scores[category] = hits
+    if not scores:
+        return FactCategory.UNKNOWN
+    return max(scores, key=lambda c: scores[c])
+
+
+def _llm_classify(content: str, llm_provider: str, model: str, llm=None) -> FactCategory:
+    if llm is None:
+        import os
+        from langchain_openai import ChatOpenAI
+        api_key = (
+            os.getenv("OPENAI_API_KEY") if llm_provider == "openai"
+            else os.getenv("ANTHROPIC_API_KEY")
+        )
+        if not api_key:
+            raise ValueError(f"No API key found for provider {llm_provider!r}")
+        llm = ChatOpenAI(model=model, temperature=0, api_key=api_key)
+
+    prompt = CLASSIFY_PROMPT.format(fact=content)
+    try:
+        from langchain_core.messages import HumanMessage
+        messages = [HumanMessage(content=prompt)]
+    except ImportError:
+        messages = [{"role": "user", "content": prompt}]
+
+    response = llm.invoke(messages)
+    raw = response.content.strip().lower()
+    try:
+        return FactCategory(raw)
+    except ValueError:
+        raise ValueError(f"LLM returned unrecognized category: {raw!r}")
+
+
+def classify_fact(
+    content: str,
+    use_llm: bool = False,
+    llm_provider: str = "openai",
+    model: str = "gpt-4o-mini",
+    llm=None,
+) -> FactCategory:
+    if use_llm:
+        try:
+            return _llm_classify(content, llm_provider, model, llm=llm)
+        except Exception:
+            pass
+    return _rule_based_classify(content)
+
+
+async def _async_llm_classify(content: str, llm_provider: str, model: str, llm=None) -> FactCategory:
+    if llm is None:
+        import os
+        from langchain_openai import ChatOpenAI
+        api_key = (
+            os.getenv("OPENAI_API_KEY") if llm_provider == "openai"
+            else os.getenv("ANTHROPIC_API_KEY")
+        )
+        if not api_key:
+            raise ValueError(f"No API key found for provider {llm_provider!r}")
+        llm = ChatOpenAI(model=model, temperature=0, api_key=api_key)
+
+    prompt = CLASSIFY_PROMPT.format(fact=content)
+    try:
+        from langchain_core.messages import HumanMessage
+        messages = [HumanMessage(content=prompt)]
+    except ImportError:
+        messages = [{"role": "user", "content": prompt}]
+
+    response = await llm.ainvoke(messages)
+    raw = response.content.strip().lower()
+    try:
+        return FactCategory(raw)
+    except ValueError:
+        raise ValueError(f"LLM returned unrecognized category: {raw!r}")
+
+
+async def classify_fact_async(
+    content: str,
+    use_llm: bool = False,
+    llm_provider: str = "openai",
+    model: str = "gpt-4o-mini",
+    llm=None,
+) -> FactCategory:
+    if use_llm:
+        try:
+            return await _async_llm_classify(content, llm_provider, model, llm=llm)
+        except Exception:
+            pass
+    return _rule_based_classify(content)

memlint/cli.py

@@ -0,0 +1,79 @@
+import sys
+
+import click
+from rich.console import Console
+from rich.table import Table
+from rich import box
+from rich.text import Text
+
+from memlint.core import StaleDetector
+from memlint.adapters.json_adapter import load_from_json
+from memlint.adapters.mem0_adapter import load_from_mem0
+from memlint.models import StalenessLevel
+
+console = Console()
+
+_LEVEL_STYLES = {
+    StalenessLevel.FRESH:   "green",
+    StalenessLevel.AGING:   "yellow",
+    StalenessLevel.STALE:   "red",
+    StalenessLevel.EXPIRED: "bold red",
+}
+
+
+@click.group()
+def main():
+    pass
+
+
+@main.command()
+@click.argument("file", type=click.Path(exists=True))
+@click.option("--only-flagged", is_flag=True, help="Show only STALE and EXPIRED facts.")
+@click.option("--json", "output_json", is_flag=True, help="Output raw JSON to stdout.")
+@click.option("--format", "fmt", default="default",
+              type=click.Choice(["default", "mem0"]), help="Input format.")
+def check(file: str, only_flagged: bool, output_json: bool, fmt: str):
+    """Check memory facts for staleness."""
+    facts = load_from_mem0(file) if fmt == "mem0" else load_from_json(file)
+
+    if not facts:
+        click.echo("No facts found in file.")
+        sys.exit(0)
+
+    report = StaleDetector().check(facts)
+
+    if output_json:
+        click.echo(report.model_dump_json(indent=2))
+        return
+
+    rows = report.flagged if only_flagged else report.results
+
+    table = Table(box=box.ROUNDED, show_header=True, header_style="bold cyan")
+    table.add_column("ID",           style="dim",    max_width=12)
+    table.add_column("Content",                      max_width=50)
+    table.add_column("Category",                     max_width=12)
+    table.add_column("Age",          justify="right", max_width=6)
+    table.add_column("Score",        justify="right", max_width=6)
+    table.add_column("Level",                        max_width=8)
+    table.add_column("Action",                       max_width=8)
+
+    for r in rows:
+        content = r.content[:47] + "..." if len(r.content) > 50 else r.content
+        table.add_row(
+            r.fact_id,
+            content,
+            r.category.value,
+            str(r.age_days),
+            f"{r.staleness_score:.2f}",
+            Text(r.staleness_level.value.upper(), style=_LEVEL_STYLES[r.staleness_level]),
+            r.recommendation,
+        )
+
+    console.print(table)
+    console.print(
+        f"\n[dim]Checked {report.total_facts} facts: "
+        f"[green]{report.fresh_count} fresh[/], "
+        f"[yellow]{report.aging_count} aging[/], "
+        f"[red]{report.stale_count} stale[/], "
+        f"[bold red]{report.expired_count} expired[/][/dim]"
+    )

memlint/core.py

@@ -0,0 +1,165 @@
+from datetime import datetime
+from memlint.models import (
+    FactCategory, MemoryFact, StalenessResult, DetectionReport, StalenessLevel,
+)
+from memlint.classifier import classify_fact, classify_fact_async
+from memlint.scorer import (
+    compute_staleness_score, determine_level, build_reason, build_recommendation,
+)
+
+
+class StaleDetector:
+    def __init__(
+        self,
+        use_llm: bool = False,
+        llm_provider: str = "openai",
+        model: str = "gpt-4o-mini",
+        llm=None,
+    ):
+        self._use_llm = use_llm
+        self._llm_provider = llm_provider
+        self._model = model
+        self._llm = llm
+
+    def _classify(self, fact: MemoryFact) -> FactCategory:
+        if fact.category is not None:
+            return fact.category
+        return classify_fact(
+            fact.content,
+            use_llm=self._use_llm,
+            llm_provider=self._llm_provider,
+            model=self._model,
+            llm=self._llm,
+        )
+
+    def check_one(
+        self,
+        fact: MemoryFact,
+        context_facts: list[MemoryFact] | None = None,
+        now: datetime | None = None,
+    ) -> StalenessResult:
+        if now is None:
+            now = datetime.utcnow()
+        all_facts = context_facts if context_facts is not None else [fact]
+        category = self._classify(fact)
+        score, has_contradiction, contradicted_by = compute_staleness_score(
+            fact, category, all_facts, now
+        )
+        level = determine_level(score)
+        reference_time = fact.last_confirmed_at or fact.created_at
+        age_days = max((now - reference_time).days, 0)
+        return StalenessResult(
+            fact_id=fact.id,
+            content=fact.content,
+            category=category,
+            staleness_score=round(score, 4),
+            staleness_level=level,
+            age_days=age_days,
+            reason=build_reason(age_days, category, fact.confirmation_count, has_contradiction, score),
+            recommendation=build_recommendation(level),
+            has_contradiction=has_contradiction,
+            contradicted_by=contradicted_by,
+        )
+
+    def check(
+        self,
+        facts: list[MemoryFact],
+        now: datetime | None = None,
+    ) -> DetectionReport:
+        if now is None:
+            now = datetime.utcnow()
+        results = [self.check_one(f, context_facts=facts, now=now) for f in facts]
+        counts: dict[StalenessLevel, int] = {level: 0 for level in StalenessLevel}
+        for r in results:
+            counts[r.staleness_level] += 1
+        return DetectionReport(
+            checked_at=now,
+            total_facts=len(facts),
+            fresh_count=counts[StalenessLevel.FRESH],
+            aging_count=counts[StalenessLevel.AGING],
+            stale_count=counts[StalenessLevel.STALE],
+            expired_count=counts[StalenessLevel.EXPIRED],
+            results=results,
+        )
+
+    def filter_safe(
+        self,
+        facts: list[MemoryFact],
+        now: datetime | None = None,
+    ) -> list[MemoryFact]:
+        report = self.check(facts, now)
+        safe_ids = {r.fact_id for r in report.safe}
+        return [f for f in facts if f.id in safe_ids]
+
+    async def _classify_async(self, fact: MemoryFact) -> FactCategory:
+        if fact.category is not None:
+            return fact.category
+        return await classify_fact_async(
+            fact.content,
+            use_llm=self._use_llm,
+            llm_provider=self._llm_provider,
+            model=self._model,
+            llm=self._llm,
+        )
+
+    async def check_one_async(
+        self,
+        fact: MemoryFact,
+        context_facts: list[MemoryFact] | None = None,
+        now: datetime | None = None,
+    ) -> StalenessResult:
+        if now is None:
+            now = datetime.utcnow()
+        all_facts = context_facts if context_facts is not None else [fact]
+        category = await self._classify_async(fact)
+        score, has_contradiction, contradicted_by = compute_staleness_score(
+            fact, category, all_facts, now
+        )
+        level = determine_level(score)
+        reference_time = fact.last_confirmed_at or fact.created_at
+        age_days = max((now - reference_time).days, 0)
+        return StalenessResult(
+            fact_id=fact.id,
+            content=fact.content,
+            category=category,
+            staleness_score=round(score, 4),
+            staleness_level=level,
+            age_days=age_days,
+            reason=build_reason(age_days, category, fact.confirmation_count, has_contradiction, score),
+            recommendation=build_recommendation(level),
+            has_contradiction=has_contradiction,
+            contradicted_by=contradicted_by,
+        )
+
+    async def check_async(
+        self,
+        facts: list[MemoryFact],
+        now: datetime | None = None,
+    ) -> DetectionReport:
+        import asyncio
+        if now is None:
+            now = datetime.utcnow()
+        results = await asyncio.gather(
+            *[self.check_one_async(f, context_facts=facts, now=now) for f in facts]
+        )
+        counts: dict[StalenessLevel, int] = {level: 0 for level in StalenessLevel}
+        for r in results:
+            counts[r.staleness_level] += 1
+        return DetectionReport(
+            checked_at=now,
+            total_facts=len(facts),
+            fresh_count=counts[StalenessLevel.FRESH],
+            aging_count=counts[StalenessLevel.AGING],
+            stale_count=counts[StalenessLevel.STALE],
+            expired_count=counts[StalenessLevel.EXPIRED],
+            results=list(results),
+        )
+
+    async def filter_safe_async(
+        self,
+        facts: list[MemoryFact],
+        now: datetime | None = None,
+    ) -> list[MemoryFact]:
+        report = await self.check_async(facts, now)
+        safe_ids = {r.fact_id for r in report.safe}
+        return [f for f in facts if f.id in safe_ids]

memlint/models.py

@@ -0,0 +1,73 @@
+from pydantic import BaseModel, Field, ConfigDict
+from datetime import datetime
+from typing import Optional
+from enum import Enum
+
+
+class FactCategory(str, Enum):
+    LOCATION = "location"
+    EMPLOYMENT = "employment"
+    PROJECT = "project"
+    PREFERENCE = "preference"
+    RELATIONSHIP = "relationship"
+    IDENTITY = "identity"
+    EPISODIC = "episodic"
+    SYSTEM_FACT = "system_fact"
+    UNKNOWN = "unknown"
+
+
+class StalenessLevel(str, Enum):
+    FRESH = "fresh"
+    AGING = "aging"
+    STALE = "stale"
+    EXPIRED = "expired"
+
+
+class MemoryFact(BaseModel):
+    model_config = ConfigDict(use_enum_values=False)
+
+    id: str
+    content: str
+    created_at: datetime
+    last_confirmed_at: Optional[datetime] = None
+    confirmation_count: int = 0
+    category: Optional[FactCategory] = None
+    source: str = "user"
+    metadata: dict = Field(default_factory=dict)
+
+
+class StalenessResult(BaseModel):
+    model_config = ConfigDict(use_enum_values=False)
+
+    fact_id: str
+    content: str
+    category: FactCategory
+    staleness_score: float
+    staleness_level: StalenessLevel
+    age_days: int
+    reason: str
+    recommendation: str
+    has_contradiction: bool = False
+    contradicted_by: Optional[str] = None
+
+
+class DetectionReport(BaseModel):
+    model_config = ConfigDict(use_enum_values=False)
+
+    checked_at: datetime
+    total_facts: int
+    fresh_count: int
+    aging_count: int
+    stale_count: int
+    expired_count: int
+    results: list[StalenessResult]
+
+    @property
+    def flagged(self) -> list[StalenessResult]:
+        return [r for r in self.results
+                if r.staleness_level in (StalenessLevel.STALE, StalenessLevel.EXPIRED)]
+
+    @property
+    def safe(self) -> list[StalenessResult]:
+        return [r for r in self.results
+                if r.staleness_level in (StalenessLevel.FRESH, StalenessLevel.AGING)]

memlint/scorer.py

@@ -0,0 +1,103 @@
+from datetime import datetime, timedelta
+from memlint.models import FactCategory, MemoryFact, StalenessLevel
+from memlint.classifier import CATEGORY_KEYWORDS
+
+DECAY_RATES: dict[FactCategory, float] = {
+    FactCategory.LOCATION:      0.0020,
+    FactCategory.EMPLOYMENT:    0.0025,
+    FactCategory.PROJECT:       0.0060,
+    FactCategory.PREFERENCE:    0.0030,
+    FactCategory.RELATIONSHIP:  0.0025,
+    FactCategory.IDENTITY:      0.0005,
+    FactCategory.EPISODIC:      0.0500,
+    FactCategory.SYSTEM_FACT:   0.0100,
+    FactCategory.UNKNOWN:       0.0030,
+}
+
+
+def determine_level(score: float) -> StalenessLevel:
+    if score < 0.30:
+        return StalenessLevel.FRESH
+    if score < 0.60:
+        return StalenessLevel.AGING
+    if score < 0.80:
+        return StalenessLevel.STALE
+    return StalenessLevel.EXPIRED
+
+
+def build_reason(
+    age_days: int,
+    category: FactCategory,
+    confirmation_count: int,
+    has_contradiction: bool,
+    score: float,
+) -> str:
+    decay_days = int(1 / DECAY_RATES[category])
+    parts = [f"{age_days} days old ({category.value} facts decay in ~{decay_days} days)"]
+    if confirmation_count > 0:
+        parts.append(f"confirmed {confirmation_count} time(s)")
+    if has_contradiction:
+        parts.append("a newer conflicting fact exists")
+    return "; ".join(parts)
+
+
+def build_recommendation(level: StalenessLevel) -> str:
+    return {
+        StalenessLevel.FRESH:   "use",
+        StalenessLevel.AGING:   "verify",
+        StalenessLevel.STALE:   "flag",
+        StalenessLevel.EXPIRED: "discard",
+    }[level]
+
+
+def _are_contradictory(
+    fact_a: MemoryFact,
+    fact_b: MemoryFact,
+    category: FactCategory,
+) -> bool:
+    if fact_a.category != fact_b.category and not (
+        fact_a.category == category or fact_b.category == category
+    ):
+        return False
+
+    time_diff = abs(fact_a.created_at - fact_b.created_at)
+    if time_diff < timedelta(days=1):
+        return False
+
+    keywords = CATEGORY_KEYWORDS.get(category, [])
+    a_lower = fact_a.content.lower()
+    b_lower = fact_b.content.lower()
+    return any(kw in a_lower and kw in b_lower for kw in keywords)
+
+
+def compute_staleness_score(
+    fact: MemoryFact,
+    category: FactCategory,
+    all_facts: list[MemoryFact],
+    now: datetime,
+) -> tuple[float, bool, str | None]:
+    """Returns (score, has_contradiction, contradicted_by_id)."""
+    reference_time = fact.last_confirmed_at or fact.created_at
+    age_days = max((now - reference_time).days, 0)
+
+    decay_rate = DECAY_RATES[category]
+    score = age_days * decay_rate
+
+    confirmation_reduction = min(fact.confirmation_count * 0.08, 0.40)
+    score -= confirmation_reduction
+
+    if fact.source == "agent_inferred":
+        score *= 1.3
+
+    has_contradiction = False
+    contradicted_by: str | None = None
+    for other in all_facts:
+        if other.id == fact.id:
+            continue
+        if _are_contradictory(fact, other, category):
+            has_contradiction = True
+            contradicted_by = other.id
+            score += 0.40
+            break
+
+    return min(max(score, 0.0), 1.0), has_contradiction, contradicted_by

memlint-0.1.0.dist-info/METADATA

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: memlint
+Version: 0.1.0
+Summary: Detect stale facts in LLM agent memory stores
+Project-URL: Homepage, https://github.com/Bhavye2003Developer/memlint
+Project-URL: Issues, https://github.com/Bhavye2003Developer/memlint/issues
+Author-email: Bhavye <bhavyedevelopment2003@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: click>=8.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-dateutil>=2.8
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: llm
+Requires-Dist: langchain-core>=0.2; extra == 'llm'
+Requires-Dist: langchain-openai>=0.1; extra == 'llm'
+Description-Content-Type: text/markdown
+
+# memlint
+
+**Lint your LLM agent's memory before it lies to you.**
+
+`memlint` detects stale facts in an LLM agent's memory store before they are injected into the context window. It scores each fact by age, confirmation history, and contradiction signals, then tells you which ones to flag, refresh, or discard.
+
+## The problem
+
+LLM agents that work across sessions store facts about the user and world - where they live, where they work, what they're building. These facts go stale when the real world changes but the memory doesn't. A fact like `"User works at xyz"` stays in memory after a job change. The agent retrieves it, injects it, and answers confidently with wrong information.
+
+`memlint` catches this before it happens.
+
+## Installation
+
+```bash
+pip install memlint
+```
+
+With optional LLM-assisted classification:
+
+```bash
+pip install memlint[llm]
+```
+
+## Quick Start
+
+```python
+from memlint import StaleDetector
+from memlint.adapters.json_adapter import load_from_json
+
+facts = load_from_json("sample_memories.json")
+detector = StaleDetector()
+report = detector.check(facts)
+
+print(f"Total: {report.total_facts} | Flagged: {len(report.flagged)}")
+for result in report.flagged:
+    print(f"  [{result.staleness_level.value.upper()}] {result.content}")
+    print(f"    Reason: {result.reason}")
+    print(f"    Action: {result.recommendation}")
+```
+
+## CLI Usage
+
+Check all facts:
+```bash
+memlint check memories.json
+```
+
+Show only stale and expired:
+```bash
+memlint check memories.json --only-flagged
+```
+
+Output raw JSON:
+```bash
+memlint check memories.json --json
+```
+
+Parse Mem0 format:
+```bash
+memlint check memories.json --format mem0
+```
+
+Sample output:
+```
+╭──────────┬────────────────────────────────────────┬────────────┬─────┬───────┬─────────┬─────────╮
+│ ID       │ Content                                │ Category   │ Age │ Score │ Level   │ Action  │
+├──────────┼────────────────────────────────────────┼────────────┼─────┼───────┼─────────┼─────────┤
+│ mem_004  │ User works at XYZ as a senior cons...  │ employment │ 279 │  0.70 │ STALE   │ flag    │
+│ mem_006  │ User debugged a LangGraph memory is... │ episodic   │  29 │  1.00 │ EXPIRED │ discard │
+╰──────────┴────────────────────────────────────────┴────────────┴─────┴───────┴─────────┴─────────╯
+
+Checked 8 facts: 1 fresh, 2 aging, 3 stale, 2 expired
+```
+
+## Staleness Score Explained
+
+Each fact is assigned a category with a natural lifespan:
+
+| Category     | Examples                              | Typical Valid Window |
+|--------------|---------------------------------------|----------------------|
+| `location`   | "lives in Delhi", "office in Sector 5"| 6–24 months          |
+| `employment` | "works at xyz", "role is consultant"  | 6–18 months          |
+| `project`    | "building pract-agents", "using Pinecone" | 1–6 months       |
+| `preference` | "prefers Python", "uses dark mode"    | 3–12 months          |
+| `relationship`| "manager is X", "team has 5 people" | 3–12 months          |
+| `identity`   | "name is X", "speaks Hindi"           | Very long/permanent  |
+| `episodic`   | "debugged a LangGraph issue today"    | Days to weeks        |
+| `system_fact`| "Python version is 3.10", "npm v9"   | 1–3 months           |
+
+Score thresholds:
+- `0.0 – 0.29` → **FRESH** (safe to use)
+- `0.30 – 0.59` → **AGING** (use with caution)
+- `0.60 – 0.79` → **STALE** (flag before injecting)
+- `0.80 – 1.0` → **EXPIRED** (do not inject without reconfirmation)
+
+## Adapters
+
+**JSON**: default format:
+```python
+from memlint.adapters.json_adapter import load_from_json
+facts = load_from_json("memories.json")
+```
+
+**Mem0**: maps `memory` to `content`, `updated_at` to `last_confirmed_at`:
+```python
+from memlint.adapters.mem0_adapter import load_from_mem0
+facts = load_from_mem0("mem0_export.json")
+```
+
+**LangChain**: two tools: `check_memory_staleness` and `filter_stale_memories` (see below).
+
+## LangChain / LangGraph Integration
+
+```python
+from memlint.adapters.langchain_tool import (
+    check_memory_staleness,
+    filter_stale_memories,
+)
+
+# In a LangGraph node: filter before injecting memories into the LLM
+safe_facts_json = filter_stale_memories.invoke({"facts_json": memories_json_string})
+```
+
+Requires `pip install memlint[llm]`.
+
+## Contributing
+
+Open an issue or pull request at the project repository.

memlint-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+memlint/__init__.py,sha256=mLVWLRdehPWe0imt5Tk97LwuXUOd7PhdgL69vxJcSGQ,386
+memlint/classifier.py,sha256=gM1Ib7EjVFKcNvu4THZ2QeTyW9O96zWAqOf0xCQGLxw,5533
+memlint/cli.py,sha256=TXbH1YO0lih4VFXpJhRRjbRlh5hj0wPZrVX9uxLez8E,2668
+memlint/core.py,sha256=kanV4fSlsuL3GPUtWSMslm6jcq9zjBCNHlo4cGJEOHs,5865
+memlint/models.py,sha256=kQMCE_Q9t63VsYkaBWQWvkV_FyGGfKnkCLXHM5sFt7A,1856
+memlint/scorer.py,sha256=paoRrYQQNVcUXhV4qI5wziqaMZpOgoK2nCQwc7hTXvY,3133
+memlint/adapters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+memlint/adapters/_utils.py,sha256=7Dy_6SPb_NAe9HNtRpKEhbC4Q-XuI4RdKHYdPvYt9Tk,234
+memlint/adapters/json_adapter.py,sha256=h-ZSfzUHu1CqAe0rQ0XPK-I9o8XTXA55QxZ9Q9UYNFA,1003
+memlint/adapters/langchain_tool.py,sha256=x7C_UNjXow5hOdy1ajF7NDAo9goS28mxNY1xtdL-PMw,924
+memlint/adapters/mem0_adapter.py,sha256=HD6DNaXjWibfa3bmSjkus-CYwUfzvp9FR0bZ0zKyPc0,994
+memlint-0.1.0.dist-info/METADATA,sha256=WFSz6abUdWJOzgec5FiYqdz8gxn97YGjmakZOkv6cZs,5787
+memlint-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+memlint-0.1.0.dist-info/entry_points.txt,sha256=H3PyyUzwn9zU5t2yB_XCQyPVUI93qtuuBUMYaarny5o,45
+memlint-0.1.0.dist-info/licenses/LICENSE,sha256=8lSgQm0jIJfk-yY3ATXdgRzUo10X0hLT9CIQqig0Ids,1091
+memlint-0.1.0.dist-info/RECORD,,

memlint-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

memlint-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+memlint = memlint.cli:main

memlint-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MatrixEscaper
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.