MemoryLint

Keep an assistant's repository memory aligned with the code.

Check saved claims against source evidence. Review what changed. Apply only the correction you approve.

Why · Quick start · Usage · Architecture · Docs

MemoryLint is a Python library and local tool for engineers building persistent coding assistants. It checks explicit claims in Markdown against the repository's package manager, declared Node version, and scripts. Every finding includes source evidence, so an assistant or a person can decide what to do next.

Why I built it

As an AI engineer, I want memory to carry evidence as well as instructions. A saved instruction can outlive the code that made it correct. I built MemoryLint to make that drift inspectable: deterministic checks for facts the repository can establish, an explanation for each finding, and a separate review step before an edit.

The problem → the solution

When this happens	MemoryLint helps by
AGENTS.md says “use npm,” but package.json declares pnpm	Flagging the saved claim and showing the declaration and source hash
Memory says jest, but the test script is now node --test	Proposing a specific replacement that you can inspect as a diff
.nvmrc and CI declare different Node versions	Reporting a conflict instead of choosing a source silently
Evidence changes while a correction is being reviewed	Rejecting an outdated patch and requiring a fresh proposal

What you get

• Evidence-backed checks for three explicit claim types, with source paths, selectors and hashes.
• Consistent reads from cached working-tree files or immutable Git commit blobs.
• Optional SQLite history with claim dependencies, scan records and review decisions.
• Reviewable corrections with hash checks, an explicit apply operation and an audit trail.
• SDK, CLI and read-only MCP for a local workflow or integration into an assistant.

Quick start

Requires Python 3.10+. The base runtime uses the standard library; no model account is needed.

Install the package

The PyPI distribution is memorylint-ai; the Python import and command remain memorylint.

python -m pip install memorylint-ai
memorylint --help
# Optional: ordinary GitHub Actions YAML support
python -m pip install 'memorylint-ai[ci]'

Try an installed CLI scan without cloning a repository:

memory_demo="$(mktemp -d)"
printf '%s\n' '{"packageManager":"pnpm@10.0.0"}' > "$memory_demo/package.json"
cat > "$memory_demo/AGENTS.md" <<'EOF'
```memorylint
{"version":1,"claims":[{"id":"manager","kind":"package_manager","value":"npm","sources":["package.json"]}]}
```
EOF
memorylint scan --repo "$memory_demo"

Expect stale_candidate, with pnpm as the proposed value, and exit 1. Use your own repository path and explicit claims for real checks. These shell snippets use bash/zsh.

Run the full source demo

The repository includes fixtures, tests and development documentation. They are also included in the source distribution; the wheel installs the library and CLI.

git clone https://github.com/Balaji91221/memorylint.git
cd memorylint
python3 -m venv .venv
source .venv/bin/activate
python -m pip install .
memorylint scan --repo examples/demo

On Windows, activate with .venv\Scripts\activate.

The authored demo deliberately has two stale claims. Expect:

Claim	Result	Evidence points to
package-manager	stale_candidate	pnpm
node-runtime	valid	22.0.0
test-command	stale_candidate	node --test

Exit 1 is the expected result: a claim needs review. Exit 0 means evaluated claims are valid; exit 2 means an unsupported or incomplete check. Scan commands do not change memory.

Local fixture output from examples/demo; this is an inspection tool, not a live-model benchmark.

Usage

Call the Python SDK

Run this from the repository root after installation:

from memorylint import scan_memory, propose_patch

result = scan_memory("examples/demo")
for finding in result.findings:
    print(finding.claim.id, finding.status, finding.proposed_value)

patch = propose_patch("examples/demo", "package-manager")
print(patch.diff)  # Review the proposed npm → pnpm change; nothing is applied.

Your Markdown needs a memorylint JSON block. Ordinary prose is not automatically asserted as true. See the claim format and source rules, SQLite history, and review/apply workflow.

Connect an MCP client

Add this server entry to a client that accepts mcpServers configuration. Replace both absolute paths with your virtual environment and target repository:

{
  "mcpServers": {
    "memorylint": {
      "command": "/absolute/memorylint/.venv/bin/memorylint",
      "args": ["serve", "--repo", "/absolute/target-repo", "--memory", "AGENTS.md"]
    }
  }
}

Call memorylint_scan with {} or memorylint_explain with {"claim_id":"package-manager"}. The server fixes the repository and memory paths at startup. It exposes read-only checks; applying corrections stays an explicit CLI/SDK operation. Protocol details →

Add optional capabilities

python -m pip install 'memorylint-ai[ci]'  # Ordinary GitHub Actions YAML support

JSON-compatible workflows need no extra. An optional extraction provider can turn selected prose into review-required candidates. Deterministic validators still check the candidates; a model cannot authorize a memory edit.

Architecture

flowchart LR
    A[CLI / Python SDK / read-only MCP] --> B[Scan orchestration]
    B --> C[Markdown claims]
    B --> D[Repository or Git snapshot]
    C --> E[Deterministic validators]
    D --> E
    E --> F[Findings and evidence]
    F -. optional .-> G[(SQLite history)]
    F --> H[Reviewable proposal]
    H --> I[Explicit apply with hash checks]

Loading

Component	Responsibility
scanner.py	Coordinate parsing, evidence reads, validation and completeness
models.py, validators.py	Keep claims, findings and deterministic comparison rules together
evidence.py, ci.py	Enforce source boundaries and parse supported declarations
index.py, review.py	Own history, proposal validation and guarded application
mcp.py, extraction.py	Provide separate read-only tool and optional provider boundaries

Read the HLD, LLD, contracts and design tradeoffs →

Deliberate boundaries

MemoryLint checks declarations, not installed runtimes or semver compatibility. Missing evidence is unresolved; arbitrary prose is not a verified fact. Corrections use optimistic concurrency, so Git snapshots are preferable when a coherent historic view matters. No hosted memory service or background rewrite is included.

Docs

Learn or build	Start here
Install, scan, review, apply and integrate	Usage guide
Understand component responsibilities and state	Architecture
Add an extraction provider	Provider contract
Check implemented scope and evidence	Implementation status
Contribute or report a vulnerability	Contributing · Security

Run the source checks from the repository root:

PYTHONPATH=src python -m unittest discover -s tests -v
PYTHONPATH=src python -m memorylint evaluate --dataset evals/heldout.json

The local source suite passed 44 tests with the optional YAML extra; a base install skips seven YAML tests. Current hosted results are in the CI badge above. Fixture replay results do not establish live-model accuracy.

MIT licensed. See LICENSE and CHANGELOG.md. Version 0.2.0 is a development release. Independent pilots and live-model quality evaluation remain separate steps.

---

Explore more of my work: latest open-source tools · recent projects.