knowledge_base.record

One knowledge record by id — candidate or curated — with every reference it names resolved: a session against the tracked session records and the ledger, a task or decision against the ledger and the task store, a commit against git, a file or test against the index and the tree, a rule, an ADR, an issue or another record against the index. Which references dangle is the question a reviewer asks before promoting, and the one the integrity validator asks of every record. A `task:none` or `decision:none` reference is refused by name.

query
behaviorally_verified
module knowledge_base
#knowledge

Exposure

Where this one definition is reachable. Absence is explicit: a surface not listed does not carry it.

surface	as
MCP	tool majordomus_knowledge_record
HTTP	GET /api/v1/knowledge/record operationId knowledge_base.record
command line	majordomus knowledge record

Schemas

The canonical input and output, from the Rust types; the MCP tool schema and the OpenAPI parameters and responses are derived from these.

input · KnowledgeRecordInput

Which knowledge record: the input of knowledge_base.record. The id is the file name and the identity the index keys the record by, so one string names it on every surface.

use majordomus_cli::capability::builtin::knowledge_base::KnowledgeRecordInput;
let input: KnowledgeRecordInput = serde_json::from_str(r#"{"id":"e1-0123456789ab"}"#).unwrap();
assert_eq!(input.id, "e1-0123456789ab");
// a key the input does not declare is refused, never ignored
assert!(serde_json::from_str::<KnowledgeRecordInput>(r#"{"id":"x","uri":"y"}"#).is_err());

property	type	required	description
id	string	yes	The record id, as the file name and `majordomus://knowledge/<id>` carry it.

JSON Schema

{
  "additionalProperties": false,
  "description": "Which knowledge record: the input of `knowledge_base.record`. The id is the file name\nand the identity the index keys the record by, so one string names it on every surface.\n\n```\nuse majordomus_cli::capability::builtin::knowledge_base::KnowledgeRecordInput;\nlet input: KnowledgeRecordInput = serde_json::from_str(r#\"{\"id\":\"e1-0123456789ab\"}\"#).unwrap();\nassert_eq!(input.id, \"e1-0123456789ab\");\n// a key the input does not declare is refused, never ignored\nassert!(serde_json::from_str::<KnowledgeRecordInput>(r#\"{\"id\":\"x\",\"uri\":\"y\"}\"#).is_err());\n```",
  "properties": {
    "id": {
      "description": "The record id, as the file name and `majordomus://knowledge/<id>` carry it.",
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "title": "KnowledgeRecordInput",
  "type": "object"
}

output · KnowledgeRecord

One knowledge record, with every reference it names resolved.

objects.get already serves the same file as metadata and content. What this adds is the resolution: which of the record's references answer, through which reader, and which dangle — the question a reviewer asks before promoting a candidate, and the question the integrity validator asks of every record.

use majordomus_cli::capability::builtin::knowledge_base::KnowledgeRecord;
let r: KnowledgeRecord = serde_json::from_str(r#"{
  "id": "e1-0123456789ab", "uri": "majordomus://knowledge/e1-0123456789ab",
  "path": ".ai/repo/knowledge/candidates/e1-0123456789ab.md", "source_class": "candidates",
  "class": "convention", "status": "candidate", "epistemics": "decided", "origin": "extracted",
  "date": "2026-09-12", "title": "An assertion", "resolved": true, "content": "---\n---\n"
}"#).unwrap();
assert!(r.derived_from.is_empty(), "a record that names nothing has nothing to resolve");
assert_eq!(r.superseded_by, None, "and is not superseded");

property	type	required	description
class	string	yes	`fact`, `convention`, `constraint`, `memory` or `lesson`.
content	string	yes	The whole file, front matter and body.
date	string	yes	The day the record reached its status.
derived_from	array	no	Every `provenance.derived_from` reference, resolved, in the record's order.
epistemics	string	yes	`observed`, `inferred` or `decided`.
id	string	yes	The record id.
origin	string	no	`authored` or `extracted`; empty when the record carries no provenance.
path	string	yes	Repository-relative path.
relations	array	no	Every `relations` entry, resolved, in the record's order.
resolved	boolean	no	True when every reference above resolved. The one bit a reviewer reads first. default false
source_class	string	yes	The source class that discovered it: `candidates` or `curated`.
status	string	yes	`candidate`, `verified` or `superseded`.
superseded_by	string \| null	no	The record that replaced this one, when the status is `superseded`.
title	string	yes	The assertion.
uri	string	yes	`majordomus://knowledge/<id>`.

JSON Schema

{
  "$defs": {
    "ReferenceResolution": {
      "description": "How a typed reference resolved.\n\nFour words and no fifth: a reference names an object of the index, or something only\nthe ledger and git can vouch for, or a file the tree no longer holds and git history\ndoes, or nothing. `external` is not a weaker `object` — a commit or a task is exactly as\nreal as a rule — it says which reader answered; `historical` resolves as well, and is\nnamed apart so a reader sees which provenance outlived its file (I1987).\n\n```\nuse majordomus_cli::capability::builtin::knowledge_base::ReferenceResolution;\nlet r: ReferenceResolution = serde_json::from_str(r#\"\"external\"\"#).unwrap();\nassert_eq!(r, ReferenceResolution::External);\nassert!(r.resolves(), \"vouched for by the ledger or git is resolved\");\nassert!(!ReferenceResolution::Missing.resolves());\n```",
      "oneOf": [
        {
          "const": "object",
          "description": "An object of the index: the `target` is its URI, or its path for a file.",
          "type": "string"
        },
        {
          "const": "external",
          "description": "Vouched for by the ledger, the task store or git: a session, a task, a decision, a commit.",
          "type": "string"
        },
        {
          "const": "historical",
          "description": "A `file:` or `test:` the tree no longer holds and git history does: cited before the\nfile was deleted, or pinned as `file:<path>@<commit>`. The `target` is the blob that\nanswers, `<commit>:<path>`, which `git show` reads.",
          "type": "string"
        },
        {
          "const": "missing",
          "description": "Nothing answers to it. A dangling reference is the integrity validator's finding.",
          "type": "string"
        }
      ]
    },
    "ResolvedReference": {
      "description": "One `derived_from` reference of a record, with how it resolved and against what.\n\n```\nuse majordomus_cli::capability::builtin::knowledge_base::{ReferenceResolution, ResolvedReference};\nlet r: ResolvedReference = serde_json::from_str(\n    r#\"{\"reference\":\"task:none\",\"resolution\":\"missing\",\"reason\":\"`none` is not a task\"}\"#,\n).unwrap();\nassert_eq!(r.resolution, ReferenceResolution::Missing);\nassert_eq!(r.target, None);\n```",
      "properties": {
        "reason": {
          "description": "Why it did not resolve, when it did not.",
          "type": "string"
        },
        "reference": {
          "description": "The reference as written: `<prefix>:<value>`.",
          "type": "string"
        },
        "resolution": {
          "$ref": "#/$defs/ReferenceResolution",
          "description": "How it resolved."
        },
        "target": {
          "description": "What it resolved to: a URI for an object, a path for a file, the reader that vouched\nfor an external reference. Absent when nothing did.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "reference",
        "resolution"
      ],
      "type": "object"
    },
    "ResolvedRelation": {
      "description": "One `relations` entry, resolved the same way.\n\n```\nuse majordomus_cli::capability::builtin::knowledge_base::{ReferenceResolution, ResolvedRelation};\nlet r: ResolvedRelation = serde_json::from_str(\n    r#\"{\"relation_type\":\"relates_to\",\"reference\":\"file:docs/CLI.md\",\"resolution\":\"object\",\"target\":\"docs/CLI.md\"}\"#,\n).unwrap();\nassert_eq!(r.relation_type, \"relates_to\");\nassert!(r.resolution.resolves());\n```",
      "properties": {
        "reason": {
          "description": "Why it did not resolve, when it did not.",
          "type": "string"
        },
        "reference": {
          "description": "The target as written.",
          "type": "string"
        },
        "relation_type": {
          "description": "`relates_to`, `depends_on`, `documents`, `supports`, `contradicts`, `supersedes` or `derived_from`.",
          "type": "string"
        },
        "resolution": {
          "$ref": "#/$defs/ReferenceResolution",
          "description": "How it resolved."
        },
        "target": {
          "description": "What it resolved to, when something did.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "relation_type",
        "reference",
        "resolution"
      ],
      "type": "object"
    }
  },
  "description": "One knowledge record, with every reference it names resolved.\n\n`objects.get` already serves the same file as metadata and content. What this adds is\nthe resolution: which of the record's references answer, through which reader, and which\ndangle — the question a reviewer asks before promoting a candidate, and the question the\nintegrity validator asks of every record.\n\n```\nuse majordomus_cli::capability::builtin::knowledge_base::KnowledgeRecord;\nlet r: KnowledgeRecord = serde_json::from_str(r#\"{\n  \"id\": \"e1-0123456789ab\", \"uri\": \"majordomus://knowledge/e1-0123456789ab\",\n  \"path\": \".ai/repo/knowledge/candidates/e1-0123456789ab.md\", \"source_class\": \"candidates\",\n  \"class\": \"convention\", \"status\": \"candidate\", \"epistemics\": \"decided\", \"origin\": \"extracted\",\n  \"date\": \"2026-09-12\", \"title\": \"An assertion\", \"resolved\": true, \"content\": \"---\\n---\\n\"\n}\"#).unwrap();\nassert!(r.derived_from.is_empty(), \"a record that names nothing has nothing to resolve\");\nassert_eq!(r.superseded_by, None, \"and is not superseded\");\n```",
  "properties": {
    "class": {
      "description": "`fact`, `convention`, `constraint`, `memory` or `lesson`.",
      "type": "string"
    },
    "content": {
      "description": "The whole file, front matter and body.",
      "type": "string"
    },
    "date": {
      "description": "The day the record reached its status.",
      "type": "string"
    },
    "derived_from": {
      "description": "Every `provenance.derived_from` reference, resolved, in the record's order.",
      "items": {
        "$ref": "#/$defs/ResolvedReference"
      },
      "type": "array"
    },
    "epistemics": {
      "description": "`observed`, `inferred` or `decided`.",
      "type": "string"
    },
    "id": {
      "description": "The record id.",
      "type": "string"
    },
    "origin": {
      "description": "`authored` or `extracted`; empty when the record carries no provenance.",
      "type": "string"
    },
    "path": {
      "description": "Repository-relative path.",
      "type": "string"
    },
    "relations": {
      "description": "Every `relations` entry, resolved, in the record's order.",
      "items": {
        "$ref": "#/$defs/ResolvedRelation"
      },
      "type": "array"
    },
    "resolved": {
      "default": false,
      "description": "True when every reference above resolved. The one bit a reviewer reads first.",
      "type": "boolean"
    },
    "source_class": {
      "description": "The source class that discovered it: `candidates` or `curated`.",
      "type": "string"
    },
    "status": {
      "description": "`candidate`, `verified` or `superseded`.",
      "type": "string"
    },
    "superseded_by": {
      "description": "The record that replaced this one, when the status is `superseded`.",
      "type": [
        "string",
        "null"
      ]
    },
    "title": {
      "description": "The assertion.",
      "type": "string"
    },
    "uri": {
      "description": "`majordomus://knowledge/<id>`.",
      "type": "string"
    }
  },
  "required": [
    "id",
    "uri",
    "path",
    "source_class",
    "class",
    "status",
    "epistemics",
    "date",
    "title",
    "content"
  ],
  "title": "KnowledgeRecord",
  "type": "object"
}

Policies

benchmark: required — a target on every transport the exposure declares; the cases are the input type's
cache: disabled — every call runs the handler

Benchmark targets

Derived from the registry for this repository: one requirement per transport, and the cases the input type provides. The whole matrix is on the benchmarks page.

transport	state	cases	targets
direct	covered	1	first-record
mcp	covered	1	first-record
http	covered	1	first-record

Claims implemented beside it

Attached by the file that implements each claim; every one links to its page with the implementation and the test that proves it.

guaranteed knowledge-served-on-every-surfaceThe candidates awaiting review, one record by id with its references resolved, and the derivation status of the checkout are one declaration each and answer with the same content over the command line, HTTP and MCPtest: apps/majordomus-cli/tests/knowledge_base.rs