memlint 0.1.1

Detect stale facts in LLM agent memory stores

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.

Works with RAG pipelines, vector databases (Pinecone, Qdrant, Chroma, Weaviate, pgvector), LangChain, LangGraph, Mem0, and any agent framework that retrieves memory before prompting.

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

pip install memlint

With optional LLM-assisted classification:

pip install memlint[llm]

memlint[llm] installs langchain-core and langchain-openai. For other backends, install the relevant LangChain integration separately:

pip install langchain-anthropic      # Anthropic Claude
pip install langchain-nvidia-ai-endpoints  # NVIDIA NIM
pip install langchain-ollama         # Ollama (local models)
pip install langchain-aws            # AWS Bedrock
pip install langchain-google-vertexai  # Google Vertex AI

Any object with an invoke() or ainvoke() method works — no LangChain dependency required.

Quick Start

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:

memlint check memories.json

Show only stale and expired:

memlint check memories.json --only-flagged

Output raw JSON:

memlint check memories.json --json

Parse Mem0 format:

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:

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:

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

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].

RAG and Vector DB Integration

Drop memlint between your vector DB retrieval step and context injection. Works with any store that returns documents with a timestamp in metadata.

from memlint import StaleDetector, MemoryFact

detector = StaleDetector()

# retrieve from any vector DB (Pinecone, Qdrant, Chroma, Weaviate, pgvector...)
results = collection.query(query_texts=[user_query], n_results=10)

facts = [
    MemoryFact(
        id=doc["id"],
        content=doc["text"],
        created_at=doc["metadata"]["created_at"],
    )
    for doc in results
]

# only inject facts that are still fresh
safe = detector.filter_safe(facts)
context = "\n".join(f.content for f in safe)

Async version for async RAG chains:

safe = await detector.filter_safe_async(facts)

Works with any LLM backend for optional classification: OpenAI, Anthropic, NVIDIA NIM, Ollama, AWS Bedrock, or any object with an invoke() / ainvoke() method.

Contributing

Open an issue or pull request at the project repository.