⚠️ Deprecated: Myco has been reborn as v0.9-genesis

This PyPI package (myco, v0.4–v0.8.x) is the Agent-First cognitive-substrate embryo: a 20-verb tool framework for an AI agent's memory. It is doctrinally a dead embryo, sealed at the git tag v0.8.8-final-embryo.

The project has been reborn as a different conception: a decades-long symbiotic partnership between one human and a substrate that carries memory, character, and doctrine across LLM model generations. v0.9 is not a pip install. It is a clone-and-build substrate (Rust + Python + TypeScript).

👉 See github.com/Battam1111/Myco

Branch v0.9-genesis, with its GETTING_STARTED.md. This myco PyPI package is no longer the project; it remains only as the predecessor lineage.

---

Myco

Devour everything. Evolve forever. You just talk.

_{Claude Code  /plugin install myco@myco  ·  Claude Desktop  myco-install host cowork  ·  Any MCP host  pip install 'myco[mcp]'}

What it is · How it lives · Quick start · Verbs · Self-validation

Languages: English · 中文 · 日本語

---

LangChain. LangGraph. CrewAI. DSPy. Claude Code skills. OpenHands. OpenClaw. Every few months the next framework drops and you migrate again.

Your notes rot too. The API you read three weeks back has changed. The doc you wrote last year is wrong now. Your AI does not even remember last week's decisions. Every new conversation starts from zero.

Now imagine one living substrate. It ingests the frameworks, the papers, the APIs, the codebases, the datasets, the decisions, the frictions. It keeps them connected in a graph the agent actually reads. It catches its own drift. It reshapes itself when your work outgrows its old form. For six months. For six years. No migration.

This is Myco.

---

What it is

Myco is a living cognitive substrate for your AI agent.

Everything the agent reads or writes, every piece of code and every paper and every decision and every friction, lives on your filesystem as plain markdown + YAML. Files cross-reference each other by name, forming a graph the agent actually reads. The agent eats raw material, digests it into integrated knowledge, immune-checks its own work against drift, propagates learning across your projects, and when the shape of the substrate no longer fits the shape of the work, reshapes the substrate itself. The kernel that runs all of this is itself a substrate, editable by default, maintained by the same agent that uses it.

Not a framework. Not a vector database. Not a managed service. A living filesystem for an agent you talk to.

The idea is older than the implementation. What changed is the agent. Today's models are finally capable of keeping their own tooling alive. Every earlier attempt at a self-maintaining knowledge system died in the same place, where the human in the loop could no longer keep up. Myco puts the loop inside the agent. Every surface, every verb, every rule assumes the maintainer is an agent, so the human in the loop is no longer load-bearing.

How it lives

You speak. The agent listens. Between your turns, Myco runs a metabolism.

• Ingestion. hunger asks what is missing. eat absorbs whatever you point at, whether a path, a URL, or a paragraph. sense and forage scan what is already here. excrete safely removes a raw note captured by mistake, moving it to an audit tombstone instead of silently deleting. intake (v0.6.0) bulk-ingests a whole directory, composing forage + eat with strict-mode failure visibility.
• Digestion. assimilate cooks raw notes into integrated knowledge. digest promotes a single note. sporulate concentrates integrated notes into a dispersible proposal.
• Circulation. traverse walks the graph and reports on its connectedness. propagate publishes learning to a downstream substrate.
• Homeostasis. immune runs a 47-dimension lint against the seven hard rules. senesce winds down each session cleanly.
• Evolution. When the substrate's shape no longer fits the work, whether a canon field is missing, a new lint dimension is needed, or a verb must change, fruit drafts a three-round craft proposal, winnow gates its shape, and molt ships the contract bump.

Twenty verbs, one manifest, two faces: a CLI for you to observe, an MCP server for the agent to drive. You memorize nothing. The agent drives.

Five principles

• Only for the agent. Every surface, every message, every verb shape is primary material for the agent. Not documentation for a human reader.
• Devour everything. No filter on intake. Missing a signal costs more than eating one too many.
• Self-evolving shape. Canon, lint dimensions, verbs, the contract itself, all of it mutable, all of it changed through a single governed craft loop.
• Nothing is final. integrated is a state, not an endpoint. Today's conclusion is tomorrow's raw material.
• Mycelium network. Every node links to every other node by traversal. Orphans are dead tissue.

The kernel IS a substrate

Myco's own source tree is a substrate. .myco/canon.yaml at .myco/. .myco/MYCO.md as the agent entry page. .docs/primordia/ holding the three-round craft document that justifies every contract bump. The Python code under src/myco/ is the innermost ring of its own ecosystem. Not a read-only artifact someone else wrote.

So the normal install clones the source and runs pip install -e on it. The agent that uses Myco is the same agent that maintains Myco. When it needs a new lint dimension, it scaffolds one with myco ramify, writes the case with myco fruit, gates the shape with myco winnow, and ships the bump with myco molt. No fork. No waiting PR. No long-lived feature branch. 永恒进化.

PyPI exists for bootstrap and for library embedding. It is not the normal install path.

Quick start

pipx run --spec 'myco[mcp]' myco-install fresh ~/myco

This clones the repository to ~/myco, runs pip install -e on it, and leaves you with a writable kernel. Then germinate a substrate inside any project:

cd your-project
myco germinate . --substrate-id your-project

Hook Myco into your agent host in one command:

• Claude Code. Run /plugin marketplace add Battam1111/Myco, then /plugin install myco@myco.
• Claude Desktop / Cowork. Run myco-install host cowork to write the MCP entry, then download myco-.zip and drag it into Claude Desktop → Settings → Plugins → Upload. Claude Desktop uploads it to your private Cowork marketplace and every subsequent session auto-installs the myco-substrate onboarding skill. (v0.7.4 hotfix: artifact extension is .zip, not .plugin — Anthropic GitHub issue #40414.)
• Any other MCP host. Run myco-install host <cursor | windsurf | zed | vscode | openclaw | claude-desktop | gemini-cli | codex-cli | goose>, or pass --all-hosts to auto-detect every host on this machine.
• Via the official MCP Registry. Use the namespace io.github.Battam1111/myco for clients that auto-resolve it.

Per-host snippets for the nine hosts with divergent schemas, Python-framework adapters (LangChain, CrewAI, DSPy, Smolagents, Agno, PraisonAI, MS Agent Framework, Claude Agent SDK), and library-embedding examples all live in INSTALL.md.

Optional extras

• pip install 'myco[mcp]' — MCP server stack (recommended baseline).
• pip install 'myco[adapters]' — PDF / HTML / URL ingestion adapters (~10 MB).
• pip install 'myco[multimedia]' — v0.8.0: audio / image-OCR / video-frame ingestion adapters. Heavy footprint (~500 MB once PyTorch + Whisper weights download); strictly opt-in. Default install stays lean — without this extras the three multimedia adapters cleanly emit install-extras failed-stubs when forage encounters a .mp3 / .png / .mp4, so eat never silently drops a media file. Image and video OCR additionally require the system tesseract binary on PATH (install via apt-get install tesseract-ocr / brew install tesseract / Windows installer).

The twenty verbs

Six subsystems. Every name is a fungal-biology term whose meaning tracks its action.

• Germination. germinate starts a fresh substrate.
• Ingestion. hunger (what is missing?), eat (absorb raw material), sense (keyword search), forage (scan ingestible paths), excrete (safely delete a raw note with an audit tombstone), intake (bulk-ingest a directory; v0.6.0).
• Digestion. assimilate (raw to integrated, in bulk), digest (promote a single note), sporulate (integrated to dispersible proposal).
• Circulation. traverse (walk the graph), propagate (publish to a downstream substrate).
• Homeostasis. immune (47-dimension lint; --fix repairs mechanically where it can).
• Cycle. senesce (session dormancy), fruit (three-round craft), winnow (gate the craft's shape), molt (ship the contract bump), ramify (scaffold a new dimension, verb, or adapter), graft (manage substrate-local plugins), brief (human-facing state rollup).

Every verb lives in src/myco/boundary/surface/manifest.yaml. The CLI (myco VERB) and the MCP tool surface both derive from that manifest mechanically. One source of truth for both faces. A downstream substrate can ramify its own dimensions or verbs into .myco/plugins/ without ever forking Myco.

Self-validation

Myco does not trust its agent to remember the contract. It enforces it.

• 47 lint dimensions across four categories: mechanical (canon invariants, write-surface, LLM-boundary, OAuth token residency, sampling gates, capability layering), shipped (package and canon version parity, kernel-ahead-of-canon), metabolic (raw backlog, stale integrated notes, sporulated-reabsorbed integrity, stale-DRAFT cleanup, shim hit-counter), semantic (graph connectedness, orphan detection, version-anchor freshness, Living Bets cadence + two-regime axis). myco immune --fix repairs mechanically where it can.
• Seven hard rules (R1 through R7) govern every session: boot ritual, session-end, sense-before-assert, eat-on-friction, cross-reference-on-creation, write-surface discipline, top-down layering. Full contract at L1_CONTRACT/protocol.md.
• Pulse sidecar. Every MCP tool response carries a substrate_pulse echoing the current contract version and a rule hint that escalates (R1, then R3, then on through the session) as the session progresses. A server-side push. The agent cannot accidentally forget.
• Write-surface enforcement. Any write outside _canon.yaml::system.write_surface.allowed is refused with WriteSurfaceViolation. Discipline as a mechanism, not as a request.

Zero host-side configuration. R1 through R7 ride inside the MCP server itself, so every client (Claude Code, Cursor, Windsurf, Zed, Codex, Gemini, Continue, Claude Desktop, OpenClaw, OpenHands) gets the same contract on boot.

Integrations

• Claude Code. Official plugin wires MCP, hooks, and slash skills in one command. Or drop .claude/ in by hand.
• Cowork (Claude Desktop local-agent-mode). Two steps: (1) myco-install host cowork writes the MCP server entry; (2) drag the .zip bundle from GitHub releases into Claude Desktop's plugin upload. Claude Desktop uploads it to your private Cowork marketplace, and every session auto-installs the myco-substrate onboarding skill so the agent follows R1 through R7 the moment it sees _canon.yaml. Cowork does not expose hooks and does not read local plugin dirs, so drag-and-drop is the only persistent path. See INSTALL.md for the full rationale.
• Any MCP host. Ten are automated via myco-install. Another nine have per-host snippets in INSTALL.md. Any other client can still run mcp-server-myco over stdio directly.
• Python agent frameworks. LangChain, CrewAI, DSPy, Smolagents, Agno, PraisonAI, MS Agent Framework, and Claude Agent SDK all consume Myco via StdioServerParameters(command="mcp-server-myco").
• Downstream substrates. myco propagate publishes. The data-driven per-host config writers live at myco.boundary.install.clients (v0.8.5 — the previous myco.boundary.host_integration adapter package was excreted as never-wired-into-production-code-paths).

Learn more

L0_VISION.md · L1_CONTRACT/ · L2_DOCTRINE/ · INSTALL.md · CONTRIBUTING.md · Issues

Architectural changes land as dated craft documents under .docs/primordia/. Every release is governed by a three-round debate, then a molt, then an auto-published fan-out to PyPI, the MCP Registry, and the GitHub release.

MIT · LICENSE · PyPI · Releases