memlint 0.1.0__tar.gz

memlint-0.1.0/.env.example

@@ -0,0 +1,3 @@
+# Optional: only needed if use_llm=True
+OPENAI_API_KEY=your_key_here
+ANTHROPIC_API_KEY=your_key_here

memlint-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+# local dev tooling
+.claude/
+CLAUDE.md
+docs/superpowers/
+stale-detector-spec.md
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+.coverage
+htmlcov/
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+
+# Env
+.env

memlint-0.1.0/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.

memlint-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,129 @@
+# 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/examples/basic_usage.py

@@ -0,0 +1,17 @@
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
+
+from memlint import StaleDetector
+from memlint.adapters.json_adapter import load_from_json
+
+facts = load_from_json(os.path.join(os.path.dirname(__file__), "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}")

memlint-0.1.0/examples/langchain_integration.py

@@ -0,0 +1,41 @@
+"""
+LangChain/LangGraph integration example.
+
+Replace the mock invocation with a real LangGraph node in production.
+Requires: pip install memlint[llm]
+"""
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
+
+try:
+    from memlint.adapters.langchain_tool import (
+        check_memory_staleness,
+        filter_stale_memories,
+        LANGCHAIN_AVAILABLE,
+    )
+except ImportError:
+    LANGCHAIN_AVAILABLE = False
+
+if not LANGCHAIN_AVAILABLE:
+    print("langchain-core not installed. Run: pip install memlint[llm]")
+    sys.exit(0)
+
+# --- Replace with real LangGraph node invocation in production ---
+sample_fact = {
+    "id": "mem_001",
+    "content": "User works at PwC",
+    "created_at": "2024-09-01T00:00:00",
+    "confirmation_count": 0,
+    "source": "user",
+}
+
+# Tool 1: check a single fact
+result_json = check_memory_staleness.invoke({"fact_json": json.dumps(sample_fact)})
+print("Single fact result:", result_json)
+
+# Tool 2: filter a list — returns only FRESH and AGING facts
+safe_json = filter_stale_memories.invoke({"facts_json": json.dumps([sample_fact])})
+print("Safe facts:", safe_json)

memlint-0.1.0/examples/sample_memories.json

@@ -0,0 +1,59 @@
+[
+  {
+    "id": "mem_001",
+    "content": "User prefers Python over JavaScript",
+    "created_at": "2026-05-20T09:00:00",
+    "last_confirmed_at": "2026-06-01T09:00:00",
+    "confirmation_count": 3,
+    "source": "user"
+  },
+  {
+    "id": "mem_002",
+    "content": "User prefers dark mode in all editors",
+    "created_at": "2026-01-28T10:00:00",
+    "confirmation_count": 0,
+    "source": "user"
+  },
+  {
+    "id": "mem_003",
+    "content": "User is based in New Delhi for work",
+    "created_at": "2025-11-19T08:00:00",
+    "confirmation_count": 0,
+    "source": "user"
+  },
+  {
+    "id": "mem_004",
+    "content": "User works at PwC as a senior consultant",
+    "created_at": "2025-08-31T09:00:00",
+    "confirmation_count": 0,
+    "source": "user"
+  },
+  {
+    "id": "mem_005",
+    "content": "User is building pract-agents using LangGraph framework",
+    "created_at": "2026-02-07T11:00:00",
+    "confirmation_count": 0,
+    "source": "user"
+  },
+  {
+    "id": "mem_006",
+    "content": "User debugged a LangGraph memory issue this morning",
+    "created_at": "2026-05-08T07:00:00",
+    "confirmation_count": 0,
+    "source": "user"
+  },
+  {
+    "id": "mem_007",
+    "content": "User lives in Delhi",
+    "created_at": "2025-05-03T10:00:00",
+    "confirmation_count": 0,
+    "source": "user"
+  },
+  {
+    "id": "mem_008",
+    "content": "User lives in Mumbai now",
+    "created_at": "2026-04-18T10:00:00",
+    "confirmation_count": 0,
+    "source": "user"
+  }
+]

memlint-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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