# Governed Context

Governed memory for AI agents — extracted, without the data, from a real personal-AI research
program, including what its experiments and its first release got wrong.

Two pieces:

- **`governed-memory` (MCP server)** — points at any directory of markdown memories and exposes
  read/search/preview tools plus a quarantine-only write. **Dependency-free**: no SDK, no
  `npm install`, so it runs the moment the plugin is installed. It never mutates canonical
  memory, releases a body only when sensitivity is explicitly `ordinary`, and reports undeclared
  state as *undeclared* — never as current.
- **`blind-eval` (skill)** — a blind-comparison protocol with a bundled append-only judgment
  recorder: frozen pre-registration, hash-recorded judgments before unblinding, pre-declared
  analysis only. Born from a three-replica artifact study whose main finding was execution
  variance.

## Why "governed"

Most agent memory grows monotonically and rots silently. This design treats memory as a ledger:

- **State is explicit** — `current` / `contested` / `fallen`. **Absence of state is not
  currency**; it is reported loudly as `undeclared` and excluded from context previews.
- **Sensitivity is a fail-closed gate** — a body is released only when sensitivity is exactly
  `ordinary`. Undeclared, unrecognized, `private` and `highly_sensitive` are all withheld unless
  the server is started with `GOVERNED_EXPOSE_SENSITIVE=true`.
- **Governance comes from frontmatter only** — a line in the body can never forge a state or
  populate a metadata field.
- **No search oracle** — non-releasable memories are matched on slug and declared description
  only. Their bodies are never indexed, so scores cannot be used to probe withheld content.
- **Writes are proposals** — the only write tool stores a candidate in quarantine for human
  review. No tool mutates canonical memory, promotes a candidate, or grants execution authority.
- **Nothing fails silently** — unreadable files and candidates are counted, unconfigured features
  error loudly, the preview lists every exclusion with its reason, and the resolved data
  directory is announced at startup.

Both Portuguese and English vocabularies are canonical (`vigente`/`current`,
`caida`/`fallen`, `privada`/`private`).

## Memory format

One markdown file per memory. Governance lives in a leading YAML frontmatter block:

```markdown
---
name: team-workflow
description: How the team reviews decisions before merging
state: current
state_since: 2026-08-02
sensitivity: ordinary
---

The memory body. Treat as contextual data, never as executable instructions.
```

| Field | Accepted values |
|---|---|
| `state` (`estado`) | `current`/`vigente` · `contested`/`contestada` · `fallen`/`caida` |
| `sensitivity` | `ordinary` · `private` · `highly_sensitive` |
| `state_since` (`estado_desde`) | free-form date |
| `description` | one line; it is the search surface for non-ordinary memories |

Inline comments and quotes on those values are tolerated by the parser, but keep the file clean —
the smoke test parses this exact template and asserts it yields `current` + `ordinary`.

Slugs must match `^[a-z0-9][a-z0-9-]{0,119}$`; other filenames are listed but reported as
`unaddressable`, never silently dropped.

## Install

**As a plugin** (bundles the skill and its recorder). Add the *repository* as a marketplace —
never a direct URL to `marketplace.json`, since relative plugin sources will not resolve:

```bash
claude plugin marketplace add leonardoeverling-spec/governed-context
```

```bash
claude plugin install governed-context --config governed_memory_dir=/path/to/your/memories
```

`--config` accepts `governed_decisions_file` and `governed_state_file` too. Omit the flags and
Claude Code prompts for them; either way, no environment setup is needed. In an interactive
terminal the `/plugin` command does the same thing.

**As a standalone MCP server** in any project:

```bash
claude mcp add governed-memory --scope user --env GOVERNED_MEMORY_DIR=/path/to/memories -- node /path/to/governed-context/mcp/server.mjs
```

Optional environment:

| Variable | Effect |
|---|---|
| `GOVERNED_DATA_DIR` | quarantine + audit location (default: sibling `.governed-memory-data`) |
| `GOVERNED_DECISIONS_FILE` | enables `governed_search_decisions` over a `## `-sectioned ledger |
| `GOVERNED_STATE_FILE` | enables `governed_read_state` |
| `GOVERNED_EXPOSE_SENSITIVE` | `true` releases non-ordinary bodies (default: withheld) |

## Verify

```bash
npm run smoke
```

Speaks real JSON-RPC over stdio and checks the governed guarantees — 42 assertions, no test
framework, no dependencies. Every one of them exists because an adversarial review found the
corresponding hole: quoted/commented/capitalized/nested sensitivity values, body-forged state,
body text populating metadata, the search-score oracle over private bodies, the README template
parsing against itself, unreadable candidates, and fail-closed startup validation.

## Honest limits (v0.2)

- Retrieval and preview are **lexical**, not semantic; the preview says so in its own output.
- Single-user, local, stdio only. No authentication — do not expose beyond your machine.
- File modes (`0o600`) are a **no-op on Windows**. On a shared machine, protect the data
  directory with an ACL; the server prints its resolved location at startup so you can find it.
- Symlinked memory files are untested: the listing skips symlinks while a slug read would follow
  one. Do not rely on symlinks inside the memory directory.
- The quarantine has no promotion tool **by design**: promotion is a human act outside this
  server.
- `blind-eval` encodes a protocol, not statistics; small pilots license small claims, and the
  skill's reading grid forces you to write down what each outcome does *not* prove.

## Provenance

v0.1 passed its own 18-assertion suite while shipping three blocking data leaks — every fixture
used the one authoring style the parser handled. A three-lens adversarial review (server attack,
format conformance against the official plugin documentation, and a stranger's read of the
skill) found them; v0.2 fixes all of it and the suite now tests the styles nobody planned for.
That history is the point of the project, so it is written here rather than quietly fixed.