okf-mcp and vord: memory and guardrails for AI agents

Code needs repeatable controls to protect its architecture, and agents need boundaries, not prompts politely asking them to behave.

This is where okf-mcp and vord fit perfectly: 🧠 okf-mcp provides structured, versioned and navigable technical memory (as a pure MCP server in Rust). 🛡️ vord provides static analysis and configurable policy validation.

The idea is not to add yet another isolated linter, but to connect context, decision, implementation and validation in a single, coherent flow.

1. The cycle starts by reading, not writing

Before an agent (or a human) modifies code, it has to map the terrain. With okf-mcp’s memory_search tool, we locate decisions and conventions through semantic search. Then memory_resolve and memory_reason retrieve the full concept and infer implicit relationships in the graph.

Memory stops being passive: it offers a vocabulary and retrievable relationships that help keep semantic consistency, reducing the risk that today the AI calls depends_on what yesterday it called requires.

2. Turning the idea into a Technical Agreement

Once the context is understood, we use spec_propose to create a spec. This document defines the problem, the expected behaviour and, crucially, the discarded alternatives.

Memory makes it possible to retrieve those discarded alternatives and the reasons behind them, lowering the odds of reopening debates that were already settled. Then spec_tasks breaks the spec down into a graph of real tasks, so they don’t drift away from their technical intent.

3. The “Kickoff” and the BDD contract as evidence 🚀

Quality doesn’t start with the first warning; it starts when the project is structured. Running vord kickoff <template> generates a base with architectural direction (React, Rust, Python, TypeScript or Fullstack Hexagonal). For existing repositories, vord init generates a vord.toml tailored to the project without having to start from a template.

But vord doesn’t only generate structure; it also prepares a BDD scaffold (features/*.feature). Before implementing, the spec’s acceptance criteria become Gherkin scenarios (behaviours, edge cases).

An important nuance: Gherkin doesn’t replace unit, integration or end-to-end tests. Vord doesn’t run the scenarios: it reads their structure and tags (@covers(...)) to check evidence and apply policies. Actually running them is still the job of the test runner the project chose. That way, Gherkin can link the spec’s intent to a verifiable evidence policy.

4. Execution under guardrails and real coverage 🚧

During implementation, Vord is designed for a very fast edit, scan and fix loop. The goal is to keep the distance between introducing a deviation and detecting it to a minimum.

vord scan analyses the workspace and reports architecture, complexity, duplication, security or repository-defined rule problems. When applicable autofixes exist, vord scan --fix can apply them; for assisted fixes on a specific issue there is vord fix.

Findings become blocking when the repository’s policy is configured that way. In environments where writes go through Vord’s hook, a change that breaks a rule or lacks the required Gherkin evidence can be denied before it lands.

Vord can also detect architectural deviations in the implementation tied to the BDD scenarios. For example, a Gherkin step that reaches infrastructure directly, instead of going through the application layer, can be reported as an architecture violation.

For broader coverage, Vord can import SARIF results from tools such as Oxlint, Ruff or Clippy and unify them in the same quality gate. And with vord flow add, the team can declare critical sequences (for example, checkout: start → stock → payment) that static analysis cannot reconstruct on its own.

Traceability isn’t automatic, but it can be made explicit: Spec → tasks → BDD scenarios → registered flows → analysis and coverage evidence.

5. Auditing and governing exceptions

Guardrails must not become a black box. Policies need traceability: what was blocked, why it was blocked, which exception was approved and who made that decision. Automation protects the flow, but responsibility for exceptions remains human.

Vord keeps a log of non-silent decisions that can be queried with vord hook audit. Escalations can require an explicit, single-use approval before a write previously denied by policy is allowed.

6. Memory health and closing the learning loop 🧠

Technical memory is only useful if it stays trustworthy. This is where graph maintenance shines:

memory_validate detects broken links, references to deleted concepts and missing embeddings.
memory_status and memory_stats provide operational visibility. Storing decisions isn’t enough; the graph that connects them has to stay navigable and consistent.

Decisions change too. With memory_history we can understand when and why a rule evolved; with memory_backlinks, assess its impact before changing it. And with memory_patch or the bulk operations, update metadata selectively. Documentation behaves like a versioned asset.

Closing the loop: the cycle closes when technical evidence flows back into memory. After a change, the team can use memory_consolidate in okf-mcp to record which Vord rules were validated, which findings were fixed, which exceptions were approved and which risks remain open. The next task no longer starts from the current code alone: it also starts from the evidence and decisions of previous changes.

💡 The core idea

okf-mcp answers one question: What do we know, what did we decide, and how does it relate? vord answers another: Does the code respect the rules, the architecture and the level of quality we expect?

Combined, they make it possible to build a complete engineering cycle, shrinking the distance between what the team knows, what it agrees to build, and what it finally verifies on disk. AI autonomy isn’t achieved just with a smarter model, but by building auditable infrastructure that channels its work.

vord and okf-mcp tools and commands

🧠 okf-mcp tools

To discover and navigate knowledge:

memory_search: finds concepts by combining text matching and semantic similarity.
memory_resolve: retrieves a full concept, its frontmatter and its related links.
memory_reason: infers implicit relationships through lightweight OWL-RL/RDFS reasoning.
memory_list: lists concepts by path or prefix, without downloading their full content.
memory_backlinks: shows which concepts point to a decision or document.

To create, version and maintain knowledge:

memory_commit: creates or updates concepts with optimistic concurrency control via CAS.
memory_patch: updates specific YAML frontmatter fields without touching the main content.
memory_bulk_commit: applies multiple commits, optionally as an atomic transaction.
memory_bulk_patch: updates the metadata of several concepts in a single operation.
memory_history: retrieves the full revision history of a concept.
memory_delete: performs a logical delete and preserves history.
memory_consolidate: keeps what happened in the session as a durable summary.

To keep the graph healthy:

memory_validate: detects broken links, deleted references and missing embeddings.
memory_status: shows the overall health of the system.
memory_stats: analyses types, tags, link hubs and orphan concepts.
memory_embed: forces embeddings to be generated or refreshed.

To work spec-driven:

spec_propose: creates a spec with agreed requirements and design.
spec_tasks: breaks a spec down into tasks linked to their origin.
spec_status: shows status, progress and tasks ready to start.

To bring in external knowledge:

skill_ingest: ingests external skills, files, folders or repositories as concepts, without passing their content through the LLM when the server has a downloader configured.

🛡️ vord MCP tools

To analyse, fix and bootstrap projects:

vord_scan: runs static analysis on the workspace and returns the findings.
vord_fix: applies autofixable corrections to detected rules.
vord_kickoff: generates a starter project from a Vord template.

For optional role-based coordination:

vord_swarm_roles: shows roles, topology and policy scope.
vord_swarm_handoff: creates, delivers or queries handoffs between roles.

Vord CLI commands

These are the most relevant commands:

vord init: creates a vord.toml configuration for an existing repository.
vord kickoff <template>: generates an initial structure for a new project.
vord scan: analyses files or directories and reports problems.
vord scan --fix: applies the available automatic fixes.
vord scan --enforce-gate: fails if the configured quality gate is not met.
vord fix: proposes an AI fix for a specific issue.
vord arch: visualises dependencies, cycles and architecture metrics.
vord flow add: registers critical flows to check coverage and drift.
vord mcp: starts the MCP server over stdio.

To enforce write policies and auditing:

vord hook install: installs the policy and hook configuration.
vord hook check <file>: evaluates a file against the policy.
vord hook claude-code: receives a proposed write and returns the policy verdict.
vord hook approve <token>: approves a single-use exception.
vord hook audit: queries the log of non-silent decisions.
vord hook reset-circuit-breaker: resets the protection circuit after human intervention.
vord hook reset-loop-guard: clears the repeated-alarm counter.

🔗 okf-mcp: github.com/pmaojo/okf-mcp · 🔗 vord: github.com/pmaojo/vord