Sentinela MCP

A lessons-learned oracle that refuses to record a "success" it can't attribute to anything but the agent's own opinion.

A Model Context Protocol server that gives coding agents a durable, cross-session memory of what worked and what didn't — with one hard rule baked into the write path: an agent cannot write its own success story.

Built by Luclino Cruz for LuCross, a one-person, AI-agent-operated holding company. Released publicly because the "no self-graded verdicts" constraint is broadly useful, not because it's a finished, install-anywhere product — see Requirements below before you assume it drops into your project.

---

The problem this solves

An agent finishes a task and reports success. Nothing verifies that claim — the next session (or the next agent) has no memory that this exact mistake was already made and already corrected, so it happily repeats it. Worse: if the agent itself gets to decide what counts as "success" and write that down as a lesson, the lesson can be wrong from the moment it's created.

This project's own dogfooding caught exactly that failure: a production run recorded a "lesson-success" note claiming "final audit validated 80/80 articles clean and compliant." An external, five-minute audit of the actual files — run minutes later — found the opposite: fabricated data still present, several articles at 2-3x the stated length limit, review verdicts copy-pasted across unrelated files. The lesson was accepted as true before anyone outside the agent had checked it.

The 3 tools

Tool	What it does
consultar_sentinela(agente, tarefa, tags)	Returns past corrections ("never repeat") and past confirmations ("worth repeating") relevant to this agent/task, read from a plain-Markdown vault — no vector DB, no embeddings, just files any tool can read.
reportar_resultado(agente, tarefa, resultado, veredito, detalhe, fonte_veredito, ...)	Records a durable lesson (success or failure) — but only if fonte_veredito is one of chairman_aprovou / chairman_corrigiu / metrica_objetiva. Anything else is refused outright. The agent that did the work cannot be the source of the verdict about the work.
session_brief(braco, dias)	Aggregates recent lessons (default: last 7 days) for injection at session start, so an agent starts a task already knowing what's already gone wrong in this area.

Why refuse self-graded verdicts instead of just trusting the agent

Because trusting it is exactly what fails. The rejection in reportar_resultado isn't a formal proof system or a second model checking the first — it's a deliberately blunt gate: if you can't point to a human approval, a human correction, or an external objective metric, the "lesson" doesn't get written. No exceptions, no "but I'm pretty confident" carve-out.

Requirements

This repo has a hard runtime dependency it does not vendor: parsers.py imports VaultValidator from a sibling vault-guardian MCP project (the write-gate that actually validates and commits a lesson to the vault) via sys.path — see the top of parsers.py. That sibling project is not published yet. Cloning this repo alone gets you:

• Full, working source for consultar_sentinela and session_brief's logic (parsers.py module load will still fail without the sibling — see below), and a complete reference for the "never accept a self-graded verdict" pattern.
• Not a turnkey install — import parsers fails at module load time (from validator import VaultValidator) until you either (a) also have a vault-guardian directory as a sibling of this one implementing the same VaultValidator.from_schema_file(path) / .validate_write(...) interface, or (b) fork this and swap that import for your own write-gate (a plain "write this Markdown file with frontmatter" function is enough to satisfy the interface parsers.py expects).

This is published as-is, honestly labeled, rather than silently pretending it's a one-command install — which would be exactly the kind of unverified claim this project exists to prevent.

Quick start (once you have a compatible vault-guardian sibling)

git clone https://github.com/luclinocruz/lucross-sentinela-mcp.git
cd lucross-sentinela-mcp
python -m venv .venv
.venv/Scripts/activate   # or: source .venv/bin/activate on Linux/macOS
pip install -r requirements.txt

Register as a project-scoped MCP server (.mcp.json in your project root):

{
  "mcpServers": {
    "sentinela": {
      "command": "/absolute/path/to/lucross-sentinela-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/lucross-sentinela-mcp/server.py"],
      "cwd": "/absolute/path/to/lucross-sentinela-mcp"
    }
  }
}

By default, legacy-memory fallback reads from ~/.claude/projects/C--Users-<you>/memory — override with the SENTINELA_MEMORY_DIR environment variable if your setup differs.

Design notes

• Plain Markdown vault, not a database. Lessons are files with YAML frontmatter (type: lesson-error / lesson-success) — readable and editable by any tool, not locked into this server.
• No neural network, no formal proof. The "rigor" here is a hard business rule (verdict source allow-list), not a model judging another model. Simple, auditable, impossible to argue around.
• Stateless per call. Every tool call reads the vault fresh — no in-memory cache to go stale or get out of sync across sessions.

License

Apache License 2.0 — see LICENSE.

Author

Luclino Cruz — github.com/luclinocruz

Built as part of the harness for LuCross, a solo-operated, AI-agent-driven company. See also lucross-sensory-grounding-mcp, the sibling project that applies the same "no self-graded verdicts" rule to visual/audio/video/text output.