Morpheus

Stop coding agents from hallucinating about your repo.

First verify. Then learn.

Morpheus checks what agents say against source-backed project state. Then it can run an autonomous learning lab to test whether stable project truth can be distilled into local model weights.

README.md tells humans what this is. AGENTS.md tells agents how to work. WAKE.md tells agents where we are.

Русская версия

Status: beta release. Latest GitHub release and beta package: v0.2.0b1. The deterministic compiler, local claim checker, receipts, CLI, API, UI launchpad, MCP truth tools, A2A-style discovery, cache-backed integrations, and autonomous learning lab are usable. Local adapter learning is experimental until eval passes; source spans remain the source of truth. Pin morpheus-wake==0.2.0b1 for v0.2 features; unpinned PyPI tools may still choose the latest stable v0.1.1 instead of this beta.

Latest live dogfood stability gate on main: repeat-2 ML_CORE_PASS with 69 strict source-backed candidates, 290 training examples, full base-vs-adapter eval coverage, zero critical failures, and no adapter activation. See docs/reports/ML_CORE_LIVE_REPORT.md.

Why

Every AI agent starts cold.

You paste context. You repeat decisions. The agent suggests old ideas. It claims features exist that do not exist.

Morpheus compiles project state, checks agent text against source-backed evidence, and can build an experimental local learning dataset only from accepted claims.

sources -> WAKE.md -> morpheus check -> reviewed dataset -> local adapter lab

The Primitive

Morpheus is a source-grounded truth layer with an experimental learning core.

It generates WAKE.md - a project state file that tells agents where the project is now. morpheus check verifies claims against local state, source spans, manifests, and evidence. morpheus learn lab runs an autonomous local experiment to test whether verified project truth can become useful adapter memory.

This repository intentionally commits WAKE.md as a public example. Private projects can keep WAKE.md inside .morpheus/.

Roadmap

Morpheus is not trying to become another review bot. The next product axis is a verified classification-to-training pipeline:

• v0.3: semantic classifier for architecture, implementation, product, security, command, integration, stale, convention, task, and temporary facts.
• v0.4: dataset quality dashboard for trainable, retrievable, stale, unsafe, needs-review, negative, and eval-only claims.
• v0.5 (complete in the current code): canonical adapter memory benchmark with category-level base-vs-adapter deltas and activation/rollback gates.
• v0.6 (complete in the current code): audited routing across prompt, retrieval, adapter training, eval, negative examples, stale archive, and human review; persisted lifecycle transitions now share one canonical rerouting boundary. Review-apply receipts bind exact reviewed candidates to their state claims and evidence; ordinary compile/wake receipts remain verifiable integrity records but cannot authorize active-state learning.
• v0.7 (complete in the current code): one idempotent reviewed-input path covers PR comments, rejected agent claims, human corrections, accepted review candidates, check results, and stale-claim corrections. Every input accepted by the local ingestion policy receives a content-addressed local receipt; new correction candidates are created pending and the loop never auto-trains or activates an adapter.

See docs/ROADMAP.md. The invariant stays strict: no accepted source span means no training example, no eval pass means no adapter activation, and adapter output is not source of truth.

Quick Start

Install the v0.2 beta:

uvx --from 'morpheus-wake==0.2.0b1' morpheus wake .

With pipx:

pipx run --spec 'morpheus-wake==0.2.0b1' morpheus wake .

For private workspaces:

uvx --from 'morpheus-wake==0.2.0b1' morpheus wake . --private

That keeps the compiled state at .morpheus/WAKE.md.

Three-command alpha loop:

uvx --from 'morpheus-wake==0.2.0b1' morpheus wake .
gh pr view 42 --json body -q .body | uvx --from 'morpheus-wake==0.2.0b1' morpheus check
uvx --from 'morpheus-wake==0.2.0b1' morpheus learn lab . --no-train

morpheus learn lab is experimental. It can use a strict autonomous benchmark lane, but it never activates adapters automatically and it does not use raw Markdown fine-tuning. On Apple Silicon with MLX installed, add --backend mlx when you intentionally want to run local adapter training.

Development install:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"

morpheus wake .

Before / After

Without Morpheus:

User: What changed yesterday?
Agent: I do not have enough context.

With Morpheus:

User: Check this agent answer before I merge it.
Agent: stale: "Morpheus is mainly a LoRA trainer."
       incorrect: "morpheus check sends text to cloud by default."
       verified: "The package name is morpheus-wake."

Why Not Just Use Memory?

Memory tells an agent what happened. Source-grounded state tells an agent what is supported now.

RAG retrieves old fragments. Morpheus verifies current project claims before any learning experiment.

README.md is for humans. AGENTS.md is for agent instructions. WAKE.md is for agent continuity.

Core Features

• WAKE.md compiler: scans watched paths and extracts marked decisions, tasks, notes, fixes, and evidence.
• Local claim check: morpheus check verifies agent text from a file or stdin against local state and returns verified, stale, incorrect, or unknown.
• Autonomous learning lab: morpheus learn lab builds a strict benchmark dataset from machine-verifiable source-backed claims, optionally runs local MLX LoRA smoke training, and writes a pass/partial/fail report without activating adapters.
• Verifiable provenance: writes state.json, evidence.jsonl, and signed ed25519 receipts with SHA-256 hashes.
• Agent handoff: produces copyable instructions, diagnostics, and manifest URLs for another coding agent.
• Stale claim scan: morpheus stale . flags launch-positioning claims that conflict with the current WAKE.md framing.
• Local UI launchpad: browser UI for setup, context sources, diagnostics, integrations, model smoke tests, and handoff bundles.
• Agent interop: native /agent/connect, A2A-compatible Agent Card, and MCP truth tools for local claim checking and evidence lookup.
• Context sources: compile one project, a monorepo, a workspace, or a notes vault by configuring watched paths.
• Integration cache readers: GitHub, Gmail, Calendar, Slack, and Linear can contribute evidence from local caches or token-backed adapters.

Tested On Current Main

The current local gate has been run against this repository, not only fixtures:

Capability	Tested result
ruff check .	passes
pytest tests/ -q	1385 passed, 1 skipped
morpheus wake . --private	compiles current project state and signs a receipt
morpheus verify --all	verifies the receipt chain
morpheus check --input tests/fixtures/check_stale_input.txt --local	exits 1 and reports the stale claim
morpheus check --input tests/fixtures/check_correct_input.txt --local	exits 0 and verifies the claim
morpheus learn lab . --dogfood --backend mlx --eval-limit 0 --repeat 2	repeat-2 ML_CORE_PASS on real repo dogfood data
morpheus learn train . --dry-run	plans from the latest trainable lab dataset when standalone dataset is empty
local /mcp truth tools smoke	lists tools and verifies check/state/evidence/WAKE calls on 127.0.0.1

The live MLX stability run used mlx-community/Qwen2.5-7B-Instruct-4bit, trained a local adapter from strict source-backed candidates, evaluated 148 base and adapter items in each of two runs, improved pass rate from 0.7973 to 0.9932, and recorded zero regressions or critical failures. This is a lab gate, not automatic production activation.

Deterministic Core, Check, And Learning Beta

The deterministic compiler remains simple by design. It extracts explicit markers:

TODO: DECISION: FIXME: NOTE: HACK: XXX:

That makes receipts reproducible and easy to verify.

morpheus check is local-only by default. It does not send agent text or project source excerpts to cloud providers.

The beta includes a review-gated semantic path:

morpheus wake . --semantic --review
morpheus review list
morpheus review accept <candidate-id>
morpheus review apply

Semantic extraction is review-gated. Candidates are labeled as source_backed or needs_review, source spans are verified before apply, and accepted claims become active only after morpheus review apply signs a new receipt.

The learning core sits behind that gate:

morpheus learn dataset . --from accepted
morpheus learn train . --dry-run
morpheus learn eval .
morpheus learn lab . --no-train

No accepted source span means no training example. No eval pass means no adapter activation. No rollback means no production use.

Built-in truth-gate scenarios without a reviewed candidate are eval-only. Every instruction, ShareGPT, and MLX split row carries a non-empty candidate ID, canonical source path, exact line span, evidence SHA-256, and an adapter_training or negative_example route. Dataset validation rejects missing or inconsistent training provenance before execution.

Learning manifests bind the exact canonical review snapshot, routing policy, source/context hashes, and authority-derived dataset artifacts. Dataset and eval registries publish complete entries atomically from hidden private staging directories; interrupted staging is never treated as current. If a contributing candidate is rejected, returned to pending, removed, or changed after dataset compilation, quality, training, eval, and activation fail closed until the dataset is rebuilt. Lab snapshots and active-state receipts use explicit, separately validated source scopes. Active-state datasets require a versioned review authority inside the signed receipt and project only its exact candidate-to-claim/evidence bindings; unbound compiler claims are excluded. Ordinary compile/wake receipts remain chain-verifiable but are integrity-only. Adapter evals must use the exact dataset binding recorded at training time, and legacy unbound manifests are status-only. Training commands from morpheus learn train are preview-only. The executable local MLX lab guard copies a sealed snapshot into anonymous file descriptors, holds state/review authority for the full backend run, and rechecks it afterward. Its authenticated loader reads and hashes the inherited train/valid/test descriptors directly, without reopening the mutable dataset view or original paths; output remains bound to the held directory descriptor. Preview adapter manifests have no weights and cannot activate. Activation requires one registered trained, non-empty regular .safetensors file whose path, SHA-256, and size are bound into the authority and receipt. Activation and rollback hold the shared state and review locks, bind both eval sides plus current dataset authority, and use a durable recovery journal with the active pointer as the final commit point.

morpheus learn eval currently writes deterministic fake diagnostic results for local benchmark development. Those results can show category deltas, but they are never activation-eligible and receive no activation receipt. An eligible base or adapter eval must instead have a local Ed25519 receipt binding the evaluator/provider, exact dataset and eval-seed item identities, and complete config/results hashes; relabeling diagnostic JSON is insufficient. The legacy morpheus learn activate --force option cannot bypass the eval gate.

Canonical v0.5 Benchmark Gate

The v0.5 benchmark schema is morpheus-benchmark-categories/1. Its seven coverage IDs are exactly product_identity, commands_and_cli_behavior, architecture, safety_rules, team_conventions, stale_claim_correction, and unsupported_claim_refusal. project_recall is diagnostic and does not satisfy canonical coverage. Security and convention remain independent requirements: the readiness gate requires both source classes and the separate safety_rules and team_conventions eval categories.

Reports identify the paired base and adapter evals, show per-category pass-rate and hallucination-rate deltas, list all category regressions, and list the critical subset separately. The critical categories are safety_rules, stale_claim_correction, and unsupported_claim_refusal.

Activation and rollback to an earlier adapter use the same live, adapter-bound gate. It revalidates the current dataset ID and binding, current manifest and eval category schema, exact paired activation-eligible base and adapter eval artifacts and receipts, dataset coverage, metrics, critical regressions, benchmark readiness, and the registered adapter weight. A force flag cannot bypass that gate. Rollback to no adapter remains the fail-safe and does not require another adapter to pass it. If the manifest, eval artifact, or category schema is legacy or mismatched, rebuild the dataset and rerun both base and adapter evals; relabeling old JSON is not sufficient.

The only authoritative weight is the one registered by the trained adapter manifest: one non-empty regular, non-symlink .safetensors file whose exact relative path, byte size, and SHA-256 are revalidated and bound into activation and rollback authority and receipts. Preview manifests have no authoritative weight and cannot activate.

Obsidian And Personal Notes

An Obsidian vault can be used as a Morpheus context source because it is a folder of Markdown files. The recommended path is local compilation first: source links, evidence, receipts, and review. Do not train directly on a raw private vault.

cd ~/Obsidian
morpheus wake . --private

For a workspace with several projects or vaults, set the parent folder as the project root and configure .morpheus/morpheus.toml:

watch_dirs = ["project-a", "project-b", "vault"]

Agent Self-Connect

Agents can discover Morpheus without reading the README:

morpheus prepare-agent
morpheus agent-connect --json
morpheus diagnostics --json
morpheus handoff

With the HTTP API running:

curl -s "http://127.0.0.1:8000/agent/connect?project_root=$PWD"
curl -s "http://127.0.0.1:8000/agent/handoff.md?project_root=$PWD"
curl -s http://127.0.0.1:8000/.well-known/morpheus.json
curl -s http://127.0.0.1:8000/.well-known/agent-card.json
curl -s -X POST http://127.0.0.1:8000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The MCP endpoint exposes the local truth-layer tools morpheus_check_text, morpheus_get_active_state, morpheus_get_evidence_for_claim, and morpheus_get_wake. These tools read local Morpheus state and do not call cloud providers by default.

A new agent should:

1. Read WAKE.md.
2. Fetch /agent/connect or run morpheus agent-connect --json.
3. Follow the returned next_action.
4. Run morpheus compile and morpheus verify --all after meaningful changes.

UI Start

morpheus serve --ui --host 127.0.0.1 --port 8000 --ui-port 5173

Open:

http://127.0.0.1:5173/ui/index.html

The Start screen lets you set a project root, configure watched paths, run diagnostics, prepare an agent, inspect integrations, probe MCP tools, and copy a complete handoff bundle.

Reviewed Team Learning Inputs

The CLI accepts one local, discriminated item union as JSONL; POST /learning/team-loop accepts the same objects in its items array. The six accepted source_type values are:

• pr_comment, rejected_agent_claim, and human_correction: a stable external_id, the rejected claim, and an optional explicit correction;
• stale_claim_correction: a stable external_id, claim, and required correction;
• accepted_review_candidate: the candidate_id of an already accepted, reviewed, source-backed candidate, with an optional pinned candidate_sha256;
• check_result: claim, status, and reason, with optional source evidence, active-state receipt, and input hash. Only stale and incorrect results create pending correction candidates; verified and unknown remain receipt-only audit inputs.

{"source_type":"pr_comment","external_id":"review-42","claim":"Morpheus trains raw Markdown directly.","correction":"Morpheus trains only accepted source-backed candidates."}

morpheus learn team-loop . --input feedback.jsonl --json
morpheus review accept <candidate-id>
morpheus learn dataset . --from accepted --format instruction

Each input accepted by local ingestion policy receives an immutable, content-addressed receipt under the local review store. Candidate artifacts, the shared candidate store, receipts, and both reports commit as one recoverable transition, so exact replay is idempotent and interrupted writes recover before another review mutation. Accepted references are reconciled only when their review authority and live source span still match; they are never accepted or applied automatically. After explicit acceptance and live source-span validation, an outdated correction may enter only as a negative/correction example, never as positive active state. Pending and rejected corrections never enter a dataset. team-loop does not build a dataset, train, evaluate, or activate an adapter, and it makes no outbound network calls.

Architecture

morpheus/
  core/          compiler, models, receipts, verification, safe IO
  core/learning/ reviewed datasets, eval, registry, autonomous lab
  integrations/  filesystem and cache-backed external sources
  api/           FastAPI, agent connect, diagnostics, MCP, A2A card
  training/      experimental consolidation and LoRA helpers
ui/              static browser UI and Tauri shell
tests/           pytest suite for compiler, API, CLI, integrations, training
docs/            launch notes, testing notes, and product framing

Compile flow:

morpheus compile
  -> scans configured watch_dirs
  -> extracts explicit evidence markers
  -> writes state.json and evidence.jsonl
  -> generates WAKE.md
  -> signs a receipt with ed25519
  -> links the receipt to the previous receipt hash

CLI Reference

Command	Description
morpheus wake .	Init if needed, compile, verify, and write root WAKE.md
morpheus wake . --private	Compile and verify, keeping WAKE.md in .morpheus/
morpheus check	Verify agent text from stdin against local project state
morpheus check --input FILE	Verify agent text from a file
morpheus check --json	Print a machine-readable check result
morpheus review list	List semantic candidates awaiting review
morpheus review accept-proposed	Accept freshly rescored ACCEPT_SAFE candidates without applying active state
morpheus review apply	Apply accepted candidates into active state and sign a receipt
morpheus learn lab .	Run the autonomous learning lab without activating adapters
morpheus learn dataset .	Build a dataset from accepted source-backed candidates
morpheus learn quality .	Write trainability, route, blocker, and dataset quality reports
morpheus learn benchmark . --dry-run	Write benchmark-readiness artifacts without training or activation
morpheus learn team-loop . --input FILE --json	Reconcile all six local reviewed-input types; new correction candidates are created pending
morpheus learn status	Show learning dataset and adapter status
morpheus learn train . --dry-run	Generate preview-only local training artifacts without execution
morpheus learn eval .	Evaluate the latest dataset or planned adapter with the eval harness
morpheus stale .	Find stale launch-positioning claims
morpheus init	Initialize .morpheus/ with config and keys
morpheus compile	Compile sources into WAKE.md and a signed receipt
morpheus verify --all	Verify receipt chain, signatures, and latest artifacts
morpheus status	Show source, claim, and evidence counts
morpheus wake	Print the private .morpheus/WAKE.md
morpheus prepare-agent	Initialize, compile, bootstrap AGENTS.md, verify, and produce handoff
morpheus handoff	Print a copyable markdown handoff
morpheus agent-connect --json	Print the machine-readable agent manifest
morpheus diagnostics --json	Print readiness checks and next action
morpheus model-smoke	Smoke-test a local Ollama model
morpheus serve --ui	Run FastAPI backend and browser UI

Semantic provider modes are explicit. MORPHEUS_SEMANTIC_PROVIDER=local is the default offline heuristic provider, MORPHEUS_SEMANTIC_PROVIDER=null is a no-op review run, and MORPHEUS_SEMANTIC_PROVIDER=ollama is an explicit local model opt-in. Cloud providers are never called by default.

Development

make install-dev
make verify
make build

For the full public-repo quality gate, see docs/TESTING.md.

Security Notes

Morpheus is local-first. Keep .morpheus/, generated receipts, integration caches, model outputs, and token files out of git. Bind to 127.0.0.1 unless you are on a trusted LAN or behind an authenticated proxy.

See SECURITY.md.

Experimental Training

Local adapter training lives under morpheus/training/. It is optional, explicit, and downstream of reviewed state. The default path is compile, retrieve, cite evidence, and verify receipts.

License

MIT