Skip to main content
Glama

Metis by Brightbeam Applied Research. Amplify your experts’ judgement. Open-source tacit memory for AI agents.

Metis is an open-source toolkit for capturing fragments of expert practice and making them available to AI agents as memory, with human review and agreed conditions for use.

Tacit fragments: a fourth layer of agent memory

A tacit fragment records what an expert noticed, how they responded, and the circumstances of that response. After human review, it sits alongside procedures, facts, and past events in the agent's memory.

Four layers of agent memory: procedural, what should happen; semantic, what is known; episodic, what happened; and tacit, what experience adds. The tacit layer comes from people.

Related MCP server: Metatron

The gap between procedure and practice

Procedures describe what should happen, and logs record what happened. The cue behind an expert's decision, and the reason for it, often go unrecorded.

Work as imagined, from SOP-17: reduce load only when the alarm threshold is crossed. Work as done, by an experienced operator on the night shift: ease back earlier, when high load meets a dull sound. Metis records what the expert noticed, the context, and the response, for people to review.

How a fragment reaches an agent

Three steps. Capture: the worker confirms the account in their own words. Human review: two named reviewers decide what the fragment may do. Use in context: the agent receives it when its conditions match. Three permission levels: Evidence, for reviewers only; Advisory, conditional support; Controlled, formal instruction.

Every capture, confirmation, review decision, and retrieval is recorded through the CHAP reference coordinator, chap-coordinator, on a hash-linked evidence chain.

The capture loop

When a recorded action differs from the procedure, a capture agent asks the expert one short question, a whisper, and the expert confirms the account in their own words.

The capture loop around the worker and the capture agent: observe, infer, whisper, confirm, store.

Seventeen kinds of know-how

Each fragment carries one of the paper's seventeen categories of tacit knowledge, K1 to K17. The atlas on the website gives an example of each and a way to capture it.

Seventeen kinds of know-how, K1 to K17, in six domains: procedural and embodied; material and equipment; perceptual; inferential; meta-cognitive; social and normative.

Quickstart: run the pump example

python -m pip install metis-memory
metis demo manufacturing-pump-vibration
metis fragment list
metis memory list
metis audit verify

The demo uses supplied observations, needs no model server, and keeps its records in ./.metis. To work from source:

git clone https://github.com/BrightbeamAI/metis && cd metis
pip install -e .
from metis import MetisEngine
from metis.conditions.context import TacitContext
from metis.consent.model import ConsentRecord, ConsentStatus

eng = MetisEngine()  # local and deterministic
eng.join_default_participants()

# Capture the operator's practice where it departs from the procedure.
frag = eng.capture_observation(
    {
        "observation_id": "OBS-1",
        "work_as_imagined": "Reduce load only when the alarm threshold is crossed.",
        "work_as_done": "Ease back earlier, when high load meets a dull sound.",
        "context": TacitContext(equipment_family="centrifugal_pump", operating_mode="high_load"),
    },
    consent=ConsentRecord(consent_status=ConsentStatus.granted),
    category="K7_sensory",
).fragment  # Evidence layer: reviewers only

# Two named reviewers promote it to Advisory.
eng.tier2_review(
    frag.fragment_id, "promoted_to_advisory", summary="advisory cue only",
    decided_by=["human:quality-lead@metis.local", "human:process-engineer@metis.local"],
)

# The gate returns it only where its conditions hold.
pump = TacitContext(equipment_family="centrifugal_pump", operating_mode="high_load", risk_class="moderate")
other = TacitContext(equipment_family="gear_pump", operating_mode="low_load", risk_class="moderate")
print(len(eng.retrieve(pump).eligible))       # 1
print(eng.retrieve(other).blocked[0].reason)  # conditions_do_not_match

Connect Metis to your application

Area

Metis provides

Your application supplies

Capture

Fragment schemas and the whisper flow

Capture tools, consent workflows, and access control

Review

Confirmation, review, and authority records

Reviewer identity and formal change control

Retrieval

The condition-aware gate and its reasons

Current context, permissions, and domain policies

Action

Guidance with its permitted uses

Action limits and human escalation

Records

Local persistence and CHAP evidence

Storage, retention, and access policy

metis mcp serves the same governed memory to MCP clients such as Claude Desktop and Claude Code, and uvx metis-memory mcp runs it with nothing installed first. See the MCP server guide. To run Metis for a team, the server guide covers sign-in, workspace roles, the web app, and PostgreSQL; deploy/ runs it with Docker or Kubernetes; and the agent integrations guide connects agents through remote MCP, a Python client, or LangChain. Connectors capture from workplace systems and put whispers in Slack or Teams, and the operations guide covers running it in production.

Learn more

  • Website: the interactive walkthrough, the atlas, and common questions.

  • Documentation: architecture, governance, retrieval, and agent use.

  • ABOUT.md: the repository map and how to develop.

  • CHAP: the Collaborative Human-Agent Protocol.

  • docs/demo.html and docs/explainer.html: an interactive demo and an illustrated explainer that open in any browser.

Ethical use

Metis captures fragments of human work with the worker's knowledge and consent. Do not use it for covert monitoring. It records no audio, video, biometrics, screenshots, or keystrokes. Production use needs worker consultation, legal review, and domain validation; read ETHICAL_USE.md first.

License

Apache-2.0. See LICENSE.

Citation

Metis is the reference implementation of Tacit Fragments: Operationalising Tacit Knowledge as a Governed Memory Layer for Agentic AI.

@article{shahid2026tacitfragments,
  title   = {Tacit Fragments: Operationalising Tacit Knowledge as a Governed Memory Layer for Agentic AI},
  author  = {Shahid, Arsalan and Suttie, Gordon and Black, Philip and Garz{\'o}n-Vico, Antonio},
  journal = {Preprints},
  year    = {2026},
  doi     = {10.20944/preprints202608.0927.v1},
  url     = {https://brightbeam.works/metis/resources/tacit-fragments-preprint.pdf}
}

Available Tools

10 tools
agent_memory_contextAssemble memory for a taskA

Assemble a task's memory in one call: the workspace's procedures (SOPs), the facts and past cases that match the context, and the governed tacit guidance that applies. Use it when starting or planning a multi-step task. For a check before a single action, use retrieve_guidance instead; calling both for one step records two decisions. Tacit guidance passes the same condition-aware gate as retrieve_guidance, and task is a label recorded with the query. When required_human_actions lists anything (an escalation, or a use constraint that calls for a person's check), stop and hand the decision to a person. Each call records the query and the gate's decisions on the evidence chain, may open an escalation task, and changes no fragment.

Inputs: task (required), context (required), role. Returns: Everything Metis holds for a task in its situation, with tacit memory gated.

answer_whisperRelay a worker's answer to a whisperA

Relay a worker's own answer to a whisper, with the consent they stated. Use it only with the choice and words of the worker the whisper is addressed to, never with your own judgement. To start a capture, use submit_observation; to dispute a stored fragment, use contest_fragment. A fragment is stored only for confirm, or correct with the worker's corrected_text, given with consent granted: it enters the Evidence layer and reaches agents only after a quorum of Mission Group reviewers promotes it. Any other answer is recorded and stores nothing. Every answer, defer included, closes the whisper, and a second answer or one from anyone but its addressee is refused.

Inputs: consent (required), response (required), whisper_id (required), answered_by (required), +1 more. Returns: What the worker's answer stored.

audit_tailRead the latest evidence-chain entriesA
Read-onlyIdempotent

Read the latest entries on the workspace's evidence chain, newest last: each gives its sequence number, method, and sender, without its content. Use it to confirm what was recorded; retrieve_guidance's recorded_at_seq appears here as an entry's seq. Raise limit to look further back; with no offset, the latest 200 entries are as far as this tool reaches. To check the chain's integrity, use audit_verify.

Inputs: limit. Returns: result

audit_verifyVerify the evidence chainA
Read-onlyIdempotent

Verify the workspace's whole hash-linked evidence chain and, when the workspace keeps an append-only ledger, check that the ledger agrees entry for entry. Use it before relying on the record, or after an incident. For the verified flag alone, use describe_workspace; to list recent entries, use audit_tail. A failed check is a normal result, verified false with the errors found, and the check reads every entry, so it takes longer as the chain grows.

Inputs: no named parameters. Returns: The result of verifying the evidence chain and its ledger.

contest_fragmentRelay a contest of a fragmentA
Destructive

Relay a person's contest of a stored fragment: challenge it, correct it, supersede it, withdraw it, or ask the worker to give the account again. Use it when a worker or reviewer says a fragment is wrong or outdated, or its contributor takes it back; to answer a pending whisper, use answer_whisper. Only the fragment's contributor may withdraw it, which revokes it at once and for good: it leaves agent-visible memory, and its history stays on the evidence chain. Every other action opens or joins a Mission Group review, and the fragment stays in use until the reviewers decide; a fragment already out of review keeps the contest on record.

Inputs: action (required), raised_by (required), rationale (required), fragment_id (required), +1 more. Returns: The recorded contest and what it set in motion.

describe_workspaceDescribe the workspaceA
Read-onlyIdempotent

Summarise the workspace this server serves: fragments per authority layer, agent-visible memory, pending whispers, Mission Group reviewers and their review rule, and whether the evidence chain verifies. Use it to orient yourself at the start of a session. It walks every hash link to report verified; for the ledger comparison and the errors found, use audit_verify, and for the memory itself, list_tacit_memory.

Inputs: no named parameters. Returns: The workspace this server serves.

list_pending_whispersList whispers awaiting an answerA
Read-onlyIdempotent

List the whispers still waiting for a worker's answer, oldest first, in one call. Use it to recover a whisper_id before relaying an answer with answer_whisper; submit_observation already returns the whisper_id, so call this only when you no longer have it. A whisper leaves the list once answered, and a deferred observation never appears because it raised none. worker filters by the exact URI given to submit_observation.

Inputs: worker. Returns: result

list_tacit_memoryList agent-visible tacit memoryA
Read-onlyIdempotent

List the tacit memory agents may receive in this workspace, as metadata with each item's conditions of applicability and review date, without the guidance text. Use it to see which situations memory covers and which context fields to give retrieve_guidance; call retrieve_guidance to receive the guidance itself. Only memory in use appears (promoted, consented, inside its review date), all in one call. Listing records nothing, and a listed item can still be withheld at retrieval when the situation, role, or risk class does not allow it.

Inputs: no named parameters. Returns: result

retrieve_guidanceRetrieve governed guidanceA

Retrieve the reviewed tacit guidance that applies to the current work situation, with the use constraints reviewers attached. Call it before acting on equipment, a process, or a product. For a whole task's procedures, reference facts, and past cases as well, use agent_memory_context; to see what memory exists without its text, use list_tacit_memory. A context field left out never matches a condition, so give every field you know. role is the role you act for: a fragment restricted to other roles is withheld as not authorised, while context.role is matched like any other condition. When required_human_actions lists anything, stop and hand the decision to a person: high and critical risk and near misses (the same equipment in a different situation) always need one, and the handover opens an escalation task (escalation_task_id). Each call records the decision on the workspace's evidence chain and changes no fragment.

Inputs: context (required), role. Returns: A governed retrieval: the guidance that applies, what was withheld and why, and…

submit_observationReport a divergence from procedureA
Idempotent

Report where a worker's action differed from the written procedure; Metis drafts one short question (a whisper) for you to put to that worker. Use it when you see or are told that work was done differently from the SOP, and relay the worker's reply with answer_whisper; to dispute a stored fragment, use contest_fragment. Metis infers a candidate account (a hypothesis) and stores no fragment until the worker answers. A worker gets at most five whispers in eight hours by default; past that budget the call returns deferred, asks nothing, and spends the id, so report it again later under a new observation_id. A retry with the same observation_id, worker, and work_as_done returns the whisper while it awaits an answer; any other report under a used id is refused. Identities are not verified here, so give the worker's real URI.

Inputs: worker (required), context (required), work_as_done (required), observation_id (required), +3 more. Returns: The whisper Metis raised for an observation, or the reason it asked nothing.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.7/5.0

    Scored across 10 tools

    Disambiguation5/5

    Each tool has a clearly delineated role: observation submission, guidance retrieval, task memory assembly, metadata listing, workspace overview, whisper management, fragment contestation, and audit functions. The descriptions explicitly cross-reference and distinguish similar tools (e.g., retrieve_guidance vs agent_memory_context vs list_tacit_memory), preventing misselection.

    Naming Consistency4/5

    Names are predominantly verb_noun in snake_case (submit_observation, retrieve_guidance, list_tacit_memory, etc.), but 'agent_memory_context' is a noun phrase and 'audit_verify'/'audit_tail' invert the verb-noun order, creating minor inconsistency.

    Tool Count5/5

    10 tools appropriately cover the server's domain of tacit knowledge governance without redundancy or thinness; each tool has a distinct purpose and the count feels well-scoped.

    Completeness5/5

    The surface covers the full lifecycle: reporting observations, generating whispers, answering/contesting fragments, retrieving guidance, listing memory, auditing the evidence chain, and summarizing the workspace. No critical gaps are apparent.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Self-hosted memory and governance layer for AI coding agents. 28 MCP tools with hybrid search, structured knowledge capture, behavioral nudges, and git-native storage. Zero cloud dependencies.
      30
      6
      Business Source 1.1
    • A
      license
      A
      quality
      B
      maintenance
      Metatron is a self-hosted system that captures a codebase's real implementation decisions — preferred patterns, rejected approaches, edge cases, internal conventions — as structured priors, and serves them to coding agents over MCP
      5
      27
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Local-first, source-grounded memory for AI agents, with citations, bitemporal history, review-gated corrections, and MCP tools for search and recall.
      4
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      MCP server that gives coding agents persistent, verified memory of codebase decisions, conventions, and skills, with evidence-based claims that are re-checked via git hooks and human-gated review. Enables memory search, propose/approve, chat harvesting, and critique across MCP-compatible tools.
      21
      87 npm
      1
      MIT