# Sentinela MCP

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

[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/protocol-MCP-purple.svg)](https://modelcontextprotocol.io)
[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/)

A [Model Context Protocol](https://modelcontextprotocol.io) 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](https://github.com/luclinocruz) for
> **[LuCross](https://github.com/luclinocruz)**, 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)

```bash
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):

```json
{
  "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](LICENSE).

## Author

**Luclino Cruz** — [github.com/luclinocruz](https://github.com/luclinocruz)

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