Metis

io.github.BrightbeamAIv0.1.6Updated Oct 5, 2026

Governed tacit memory for AI agents: reviewed expert know-how, given only where conditions match

VerifiedSTDIODesktop onlyAI & ML Security & Monitoring Knowledge & Memory

Overview

AI-generated overview

Metis serves governed tacit expert memory to AI agents, releasing reviewed know-how only when its stated conditions match.

What it does: Metis captures tacit fragments of expert practice — what someone noticed, how they responded, and under what circumstances — and stores them alongside procedures, facts, and past events. Fragments pass through human confirmation and review before becoming advisory, and every capture, review decision, and retrieval is recorded on a hash-linked evidence chain. A condition-aware gate returns a fragment only where its context conditions hold, and otherwise reports why it was blocked. It runs locally and deterministically, and can serve the same governed memory to MCP clients.
When to use it: Use it when an assistant should draw on reviewed human expertise rather than generic procedure text, and when retrieval must be limited to situations the expert's conditions actually cover. It suits teams that need an auditable record of how know-how was captured, approved, and released. A bundled pump demo lets you try governed memory without a model server.
Requirements: Runs as a local process over stdio, launched with uvx from the metis-memory PyPI package, so Python and uv are needed. The METIS_HOME environment variable is required and names the Metis project directory to serve; a directory without a workspace gets the pump demo. No authentication is declared. Desktop only.

Before you install

It captures fragments of human work, so the README warns against covert monitoring and says production use needs worker consultation, legal review, and domain validation. It states that no audio, video, biometrics, screenshots, or keystrokes are recorded. Reviewers are named in review records, and the README assigns storage, retention, and access policy to your application. Read ETHICAL_USE.md before production use.

Installation

In SourceWeft

Open Metis in the dashboard and add it to a workspace.
Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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

Website · Documentation · Paper · PyPI · CHAP

[PyPI version] [Python 3.10+] [Apache-2.0] [Recorded with CHAP] [Metis MCP server on Glama]

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.]

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

bash

python -m pip install metis-memorymetis demo manufacturing-pump-vibrationmetis fragment listmetis memory listmetis audit verify

python -m pip install metis-memorymetis demo manufacturing-pump-vibrationmetis fragment listmetis memory listmetis audit verify

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

Python example: capture, review, and the condition-aware gate

python

from metis import MetisEnginefrom metis.conditions.context import TacitContextfrom metis.consent.model import ConsentRecord, ConsentStatus
eng = MetisEngine()  # local and deterministiceng.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:[email protected]", "human:[email protected]"],)
# 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))       # 1print(eng.retrieve(other).blocked[0].reason)  # conditions_do_not_match

from metis import MetisEnginefrom metis.conditions.context import TacitContextfrom metis.consent.model import ConsentRecord, ConsentStatus
eng = MetisEngine()  # local and deterministiceng.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:[email protected]", "human:[email protected]"],)
# 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))       # 1print(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.

bibtex

@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://metis.brightbeam.works/resources/tacit-fragments-preprint.pdf}}

@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://metis.brightbeam.works/resources/tacit-fragments-preprint.pdf}}

Source: README.md at commit 0209398

Tools

Tool metadata has not been indexed yet.

Version history

v0.1.6LatestOct 5, 2026