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:

---
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:

claude plugin marketplace add leonardoeverling-spec/governed-context

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:

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

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.