QA Memory
JeanSantos89/QA-memory
Conhecimento QA institucional como MCP server local e queryável
Ver no GitHubMCP server que funciona como camada de conhecimento semântico para times de QA, armazenando contexto persistente de produto (regras de negócio, fluxos críticos, incidentes) para guiar workflows de desenvolvimento com agentes autônomos. Elimina perda de conhecimento institucional e oferece análise de risco e impacto diretamente no seu assistente de IA.
Instalação
npx convez-ai JeanSantos89/QA-memory1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Gerar planos de teste baseados em conhecimento histórico do produto
- Analisar risco e impacto de mudanças antes do merge
- Onboard rápido de QA engineers consultando comportamentos e regras do produto
- Detectar conflitos entre regras de negócio e mudanças propostas
Veredito

Ferramenta sólida para times de QA que enfrentam perda de conhecimento institucional. A abordagem local (sem nuvem) e integração com MCP é sensata para dados sensíveis. Ainda em alpha, mas com cobertura de testes robusta (113+ Vitest, 79+ pytest) e arquitetura TypeScript/Python bem estruturada.
README
A tradução para o português deste README ainda está na fila.
qa-memory
What it does · Setup · Workflows · MCP Tools · Token Economy
QA institutional knowledge as a local MCP server — feed it specs, Jira tasks and Confluence pages, get risk scores, impact analysis and test plans directly from your AI coding assistant.
QA engineers build deep product knowledge over time: what the edge cases are, what breaks when you touch a certain area, what the business rules actually are (not what the docs say). That knowledge lives in people's heads and spreadsheets and gets lost when someone leaves or a new dev asks "is it safe to change this?"
qa-memory captures that knowledge in a local database and makes it queryable by your AI coding assistant. Ask it "what's the risk of touching checkout?" or "generate a test plan for this Jira task" and it answers from everything your team already knows — without sending your product data to the cloud.
Why this matters
For QA engineers
- Stop writing test plans from scratch. The assistant reads the Jira task, checks what already broke in that area, and produces a focused plan: new cases + regression targets, ranked by criticality.
- Your hard-won knowledge compounds. Every incident recorded, every rule confirmed, makes the next test plan better.
- You stay in control. The system proposes; you approve. Nothing gets marked "QA-confirmed" without your sign-off.
For engineering teams
- Know the risk before merging. "What might break if we change the cancellation window?" returns a concrete answer, not a shrug.
- Onboard faster. A new QA or dev can query what the product actually does in any area, distilled from specs and tickets your team already processed.
- Catch regressions earlier. Impact analysis flags which existing rules conflict with a proposed change before it ships.
What it does
- Remembers product knowledge — behaviors (what the product does) and rules (constraints, business logic) extracted from specs, Jira tasks, Confluence pages, and PDFs.
- Scores risk — given a feature area or file path, returns a risk score, the relevant behaviors, their rules, and the history of what already broke there.
- Analyzes impact — given a proposed change in plain language, reasons about what may break, what to watch when testing, and which existing rules conflict.
- Curates itself — a memory-keeper agent reviews inferred rules, detects duplicates, and proposes promotions to QA-confirmed. You stay in control; it proposes, you approve.
- Works locally — embeddings run via
sentence-transformers(no API required). LLM extraction works with Anthropic, Gemini, or a local Ollama model. Your product knowledge never leaves your machine unless you choose otherwise.
How you'll use it day-to-day
Feed knowledge from a Jira task or Confluence page
"Read PROJ-456 and save the product rules to memory."
The assistant fetches the task, structures it as behaviors + rules, and persists it — no LLM cost if you're using Claude Code, since Claude itself does the extraction and calls feed_to_memory directly.
Assess risk before testing
"What's the risk of touching the checkout payment flow?"
Returns a risk score, the matched behaviors, their business rules, and any incidents recorded in that area (what already broke, when, and how bad).
Generate a test plan for a task
"Create a test plan for PROJ-789 — consider the new functionality and what might regress."
The assistant reads the task, checks risk for all affected areas, analyzes the proposed change, and generates a plan split into new cases (what the task adds) and regression cases (what might break, ranked by criticality and incident history).
Analyze the impact of a change
"What breaks if we allow free cancellation up to 5 minutes after the restaurant accepts?"
Returns what may break, what to watch when testing, and which existing rules conflict — reasoned against everything already in memory.
Record an incident
"The order status badge didn't update after cancellation — log this as a P1 incident."
Lifts the risk score for that area. Future test plans will flag it as a known breakage point.
Prerequisites
| Tool | Version | Notes |
|---|---|---|
| Node.js | ≥ 20 | |
| pnpm | any | npm i -g pnpm if not installed |
| uv | any | docs.astral.sh/uv |
| Ollama | optional | For fully local LLM extraction — ollama.com |
Installation
# Windows
git clone https://github.com/JeanSantos89/QA-memory.git && cd QA-memory
pwsh -File scripts/install.ps1
# macOS / Linux
git clone https://github.com/JeanSantos89/QA-memory.git && cd QA-memory
./scripts/install.sh
The script:
- Checks prerequisites
- Installs and builds the MCP server (TypeScript)
- Installs the ingestion package (Python)
- Initializes your local instance at
.qa-memory/(git-ignored — your product knowledge stays private) - Prints the MCP config snippet to paste into Claude Code
Flags: --check (only verify prerequisites), --no-seed (skip dogfood data).
Connecting to your AI assistant
Option A — Claude Code (recommended)
After install, paste the printed snippet into your Claude Code MCP settings (.mcp.json in your project root):
{
"mcpServers": {
"qa-memory": {
"command": "node",
"args": ["/path/to/QA-memory/packages/mcp-server/dist/index.js"],
"env": {
"QA_MEMORY_DB": "/path/to/QA-memory/.qa-memory/qa-memory.db",
"QA_MEMORY_LLM": "anthropic",
"QA_MEMORY_LLM_MODEL": "claude-haiku-4-5-20251001"
}
}
}
}
Once connected, Claude Code can call all memory tools directly during your conversation — no extra steps.
Option B — Any MCP-compatible client with an API key
Set QA_MEMORY_LLM to your preferred provider and supply the API key as an environment variable:
{
"mcpServers": {
"qa-memory": {
"command": "node",
"args": ["/path/to/QA-memory/packages/mcp-server/dist/index.js"],
"env": {
"QA_MEMORY_DB": "/path/to/.qa-memory/qa-memory.db",
"QA_MEMORY_LLM": "gemini",
"QA_MEMORY_LLM_MODEL": "gemini-2.5-flash",
"GEMINI_API_KEY": "your-key-here"
}
}
}
}
Option C — Fully local (no API key)
Run extraction entirely on your machine with Ollama:
{
"env": {
"QA_MEMORY_LLM": "ollama",
"QA_MEMORY_LLM_MODEL": "qwen2.5:14b"
}
}
qwen2.5:14b is the recommended local model. The 8B variant works for extraction; 14B+ is needed for reliable impact analysis.
Configuration
All configuration via environment variables:
| Variable | Default | Description |
|---|---|---|
QA_MEMORY_DB | .qa-memory/qa-memory.db | Path to the SQLite database |
QA_MEMORY_LLM | anthropic | LLM provider: anthropic | gemini | ollama |
QA_MEMORY_LLM_MODEL | provider default | Model override (e.g. qwen2.5:14b for Ollama) |
QA_MEMORY_LANG | en | Output language: en | pt-BR |
QA_MEMORY_INGESTION_DIR | package path | Path to the ingestion package (auto-detected) |
MCP Tools
Once connected, these tools are available to your AI assistant:
| Tool | What it does |
|---|---|
feed_to_memory | Persist behaviors + rules from structured JSON — no LLM call (the assistant is the extractor). Use this for Jira/Confluence content already in context. |
add_to_memory | Ingest raw text, a local file, or a public URL — LLM extracts behaviors + rules internally. |
query_behavior | Search product behaviors by free text. |
query_risk | Get a risk score + matched behaviors + rules for a feature area or file path. |
analyze_impact | Reason about a proposed change: what may break, what to watch, which rules conflict. |
map_area | Associate a file glob (e.g. checkout/**/*.ts) with its behaviors so query_risk can resolve by path. |
update_rule | Define or override a rule in QA voice (pins it as confirmed, confidence 1.0). |
record_incident | Record something that broke — lifts the risk score for that area with recency + severity weighting. |
review_memory | List inferred rules awaiting QA confirmation (the memory-keeper's worklist). |
find_duplicate_rules | Detect clusters of near-duplicate rules across behaviors. |
retire_rule | Retire a redundant rule (sets status to superseded, removes from all reads). |
Token Economy
qa-memory was designed from the start to minimize LLM token usage. Every architectural decision trades verbosity for efficiency.
feed_to_memory — zero LLM cost
When content is already in your assistant's context (a Jira task you pasted, a Confluence page you fetched), the assistant itself does the extraction and calls feed_to_memory with structured JSON. No internal LLM call is made — it's a direct write to SQLite. Use add_to_memory only for raw URLs or local files the assistant can't read directly.
Two-pass extraction pipeline Ingestion runs a summary pass first (≤ 150 tokens per chunk) to decide relevance, then a full extraction pass only on chunks that score above the threshold. Irrelevant content never reaches the expensive step.
Cheapest model per provider
The default extraction model is always the cheapest available: claude-haiku-4-5 for Anthropic, gemini-2.5-flash for Gemini, qwen2.5:14b locally via Ollama. Configurable via QA_MEMORY_LLM_MODEL — upgrade only when quality demands it.
Terse internal prompts
All prompts inside the ingestion pipeline are written in a compressed, instruction-only style. No filler, no hedging, no chain-of-thought padding. The same principle applies to how Claude Code is configured to interact with this project (see CLAUDE.md).
Embeddings run locally
Semantic search uses all-MiniLM-L6-v2 via sentence-transformers — no API call, no tokens billed. Risk scoring and behavior lookup are free at query time.
Token budget is enforced Each sync run has a configurable token budget (default: 50k tokens). The pipeline tracks input + output tokens per LLM call and stops cleanly when the budget is exhausted, resuming on the next run.
Privacy
Your product knowledge lives in .qa-memory/ which is git-ignored. The repo contains only neutral code and documentation — no company names, internal URLs, real ticket keys, or customer data. Clone it, point it at your product, and your knowledge stays local.
To protect against accidental leaks, copy .githooks/neutrality.local.example to .githooks/neutrality.local and fill in your company-specific terms. The pre-commit and pre-push hooks will block any staged content that matches.
Project structure
packages/
mcp-server/ TypeScript — MCP server, tools, search, risk scoring, embedder
ingestion/ Python — LLM extraction pipeline, PDF/URL sources, impact analysis
scripts/
install.ps1 Windows setup
install.sh macOS/Linux setup
docs/
STATE.md Current development status (living doc)
SCHEMA.md SQLite schema source of truth
DECISIONS.md Architecture decision log
.githooks/ Commit/push guards (doc enforcement, neutrality scan)
.qa-memory/ Your local instance — git-ignored, never committed
Development
# MCP server (TypeScript)
cd packages/mcp-server
pnpm install && pnpm build
pnpm test # Vitest
pnpm typecheck # tsc --noEmit
# Ingestion (Python)
cd packages/ingestion
uv sync
uv run pytest
uv run ruff check src/
uv run mypy src/
Commit discipline: one block = code + tests + living doc update in the same commit. The pre-commit hook blocks code changes without a corresponding doc update.