@goondocks/myco 0.1.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,22 @@
+{
+  "name": "myco-plugins",
+  "owner": {
+    "name": "goondocks-co"
+  },
+  "metadata": {
+    "description": "Myco — collective agent intelligence plugins"
+  },
+  "plugins": [
+    {
+      "name": "myco",
+      "source": {
+        "source": "npm",
+        "package": "@goondocks/myco"
+      },
+      "description": "Collective agent intelligence — captures session knowledge and serves it back via MCP",
+      "license": "MIT",
+      "keywords": ["intelligence", "memory", "mcp", "sessions", "team", "knowledge"],
+      "category": "productivity"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "myco",
+  "version": "0.1.0",
+  "description": "Collective agent intelligence — captures session knowledge and serves it back to your team via MCP",
+  "author": {
+    "name": "goondocks-co",
+    "url": "https://github.com/goondocks-co"
+  },
+  "license": "MIT",
+  "keywords": ["intelligence", "memory", "mcp", "sessions", "team", "knowledge"],
+  "mcpServers": {
+    "myco": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/dist/src/mcp/server.js"],
+      "env": {}
+    }
+  }
+}

package/CONTRIBUTING.md

@@ -0,0 +1,143 @@
+# Contributing to Myco
+
+Myco is a plugin for collective agent intelligence, supporting Claude Code and Cursor. This guide covers development setup and project conventions. For architecture details, see [Lifecycle docs](docs/lifecycle.md).
+
+## Installing Myco (End Users)
+
+```bash
+claude plugin marketplace add goondocks-co/myco
+claude plugin install myco@myco-plugins
+```
+
+Then in any project:
+
+```
+/myco-init
+```
+
+This sets up the vault, configures your LLM backend, and starts capturing session knowledge.
+
+### Requirements
+
+- Node.js 22+
+- Claude Code or Cursor
+- An LLM backend: [Ollama](https://ollama.com) (recommended) or an Anthropic API key
+
+For Ollama, pull the recommended models:
+
+```bash
+ollama pull gpt-oss
+ollama pull nomic-embed-text
+```
+
+## Development Setup
+
+### 1. Clone and install
+
+```bash
+git clone https://github.com/goondocks-co/myco.git
+cd myco
+npm install
+```
+
+### 2. Run locally
+
+For **active development** (per-session, no install needed):
+
+```bash
+claude --plugin-dir /path/to/myco
+```
+
+For **persistent local dev** (survives across sessions):
+
+```bash
+claude plugin marketplace add /path/to/myco/.claude-plugin
+claude plugin install myco
+```
+
+### 3. Initialize the vault
+
+```
+/myco-init
+```
+
+For dogfooding, the vault lives at `~/.myco/vaults/myco/` (configured via `MYCO_VAULT_DIR` in `.claude/settings.json`).
+
+### 4. Verify
+
+```
+/myco-status
+```
+
+## Development Workflow
+
+### Build and test
+
+```bash
+make build             # lint + test + tsc + copy templates
+make check             # lint + test only (pre-commit gate)
+make watch             # tsc watch mode
+make clean             # remove dist/
+```
+
+### After code changes
+
+Hooks pick up new code on the next invocation. The daemon must be restarted separately:
+
+```bash
+make build && node dist/src/cli.js restart
+```
+
+## Project Structure
+
+```
+myco/
+├── .claude-plugin/        # Claude Code + VS Code plugin manifest + marketplace
+├── .cursor-plugin/        # Cursor plugin manifest + marketplace
+├── hooks/                 # Hook registration shell scripts
+├── commands/              # Slash commands (/myco-init, /myco-status, /myco-setup-llm)
+├── skills/                # Agent skills
+├── src/
+│   ├── agents/            # Agent adapters (Claude Code, Cursor) — transcript parsing + image capture
+│   ├── capture/           # Event buffering + buffer-based turn fallback
+│   ├── config/            # Config schema and loader
+│   ├── context/           # Context injection for UserPromptSubmit hook
+│   ├── daemon/            # Long-lived HTTP daemon: session lifecycle, batch processing, plan watching
+│   ├── hooks/             # Hook entry points (thin — delegate to daemon)
+│   ├── index/             # SQLite FTS5 + sqlite-vec vector search
+│   ├── intelligence/      # LLM backends (Ollama, LM Studio, Anthropic)
+│   ├── mcp/               # MCP server + tool handlers
+│   ├── prompts/           # LLM prompt templates
+│   └── vault/             # Reader, writer, Zod schemas for vault notes
+├── tests/                 # Mirrors src/ structure
+├── docs/                  # Lifecycle, quickstart, doc site
+└── Makefile               # Dev shortcuts
+```
+
+## Architecture
+
+See [docs/lifecycle.md](docs/lifecycle.md) for the full lifecycle with diagrams. Key points:
+
+- **Hooks are thin** — they delegate to the daemon via HTTP. No business logic in hooks.
+- **The daemon is the authority** — all event processing, session note writing, and observation extraction happen there.
+- **Transcripts are the source of truth** — session conversation turns are read from the agent's native transcript file (Claude Code `.jsonl`, Cursor `.txt`/`.jsonl`), not from Myco's event buffer. The buffer is the fallback when no transcript is available.
+- **Session notes are rebuilt** — on each stop event, the full conversation is re-parsed from the transcript and the session note is regenerated. Data preservation is guaranteed by the transcript being append-only.
+
+## Distribution
+
+Published as `@goondocks/myco` on [npmjs.org](https://www.npmjs.com/package/@goondocks/myco).
+
+1. Push to `main` — CI runs lint + tests
+2. Tag a release (`v0.x.y`) — triggers the publish workflow
+3. `npm publish` builds and pushes to npmjs.org
+4. Users get the new version via `claude plugin update myco`
+
+## Conventions
+
+- TypeScript strict mode, ES modules
+- Plain `tsc` for build (native deps like `better-sqlite3` can't be bundled)
+- `make check` must pass before committing
+- Prompt templates are markdown with `{{placeholder}}` syntax
+- Config is YAML (`myco.yaml`), vault notes are markdown with YAML frontmatter
+- No magic literals — extract named constants
+- Idempotent operations by default

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Goondocks Consulting
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,74 @@
+<p align="center">
+  <img src="assets/hero-wide.svg" alt="Myco" width="100%">
+</p>
+
+<p align="center">
+  <strong>The connected intelligence layer for agents and AI-assisted teams</strong>
+</p>
+
+<p align="center">
+  <a href="https://github.com/goondocks-co/myco/actions/workflows/ci.yml"><img src="https://github.com/goondocks-co/myco/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/goondocks-co/myco/actions/workflows/publish.yml"><img src="https://github.com/goondocks-co/myco/actions/workflows/publish.yml/badge.svg" alt="Release"></a>
+  <a href="https://github.com/goondocks-co/myco/releases/latest"><img src="https://img.shields.io/github/v/release/goondocks-co/myco?label=version&color=22c55e" alt="Version"></a>
+  <a href="https://github.com/goondocks-co/myco/blob/main/LICENSE"><img src="https://img.shields.io/github/license/goondocks-co/myco?color=22c55e" alt="License"></a>
+  <img src="https://img.shields.io/badge/node-%3E%3D22-22c55e" alt="Node 22+">
+  <img src="https://img.shields.io/badge/agents-Claude%20%7C%20Cursor%20%7C%20VS%20Code-22c55e" alt="Claude | Cursor | VS Code">
+</p>
+
+```bash
+# Add the Myco marketplace and install
+claude plugin marketplace add goondocks-co/myco
+claude plugin install myco@myco-plugins
+```
+
+Then initialize in your project:
+```
+> /myco-init
+```
+
+The agent sets up your vault, configures intelligence, and starts capturing. Works with Claude Code and Cursor out of the box.
+
+## What is Myco?
+
+Myco captures everything your AI agents do — sessions, decisions, plans, discoveries — and connects them into a searchable intelligence graph stored as an [Obsidian](https://obsidian.md) vault. Named after [mycorrhizal networks](https://en.wikipedia.org/wiki/Mycorrhizal_network), the underground fungal systems that connect trees in a forest, Myco is the invisible network linking your agents and team members, sharing intelligence beneath the surface.
+
+**For agents** — MCP tools let any agent runtime search, recall, and build on your team's accumulated knowledge.
+```
+myco_search("how did we handle auth?")  → semantically matched sessions, decisions, and linked context
+myco_recall("migration plan")           → full decision history with session lineage
+myco_remember(observation)              → persist a discovery for the team
+```
+
+**For humans** — open the vault in Obsidian and browse the intelligence graph visually. Sessions link to plans, plans link to decisions, decisions link to memories. It's all Markdown with backlinks — your team's connected knowledge, navigable and searchable.
+
+**For teams** — the vault is a Git-friendly directory of Markdown files. Share it through your existing Git workflow.
+
+## How it works
+
+### Capture
+
+A background daemon reads your agent's conversation transcript after each turn — the full dialogue including prompts, AI responses, tool calls, and screenshots. Observations (decisions, gotchas, discoveries) are extracted automatically via a local LLM and written as linked vault notes.
+
+### Index
+
+Every note is indexed for both keyword search (SQLite FTS5) and semantic search (vector embeddings via Ollama or LM Studio). The index is fully rebuildable from the Markdown source of truth.
+
+### Serve
+
+An MCP server exposes the vault to any agent runtime. Relevant memories are injected into every prompt automatically — no manual lookup needed. Agents build on your team's accumulated knowledge without being told to.
+
+### Connect
+
+Sessions link to plans. Plans link to decisions. Decisions link to memories. Obsidian backlinks and metadata create a navigable graph of your team's institutional knowledge. Open the vault in [Obsidian](https://obsidian.md) to browse it visually, or let agents traverse it via MCP tools.
+
+### Multi-agent
+
+Myco reads conversation transcripts from Claude Code, Cursor, and any agent that writes JSONL transcripts. Screenshots shared during sessions are extracted and embedded as Obsidian image attachments. A plugin adapter registry makes adding new agents straightforward.
+
+## Contributing
+
+Contributions welcome. See the [Contributing Guide](CONTRIBUTING.md) for development setup, and the [Lifecycle docs](docs/lifecycle.md) for architecture details. Please open an issue to discuss before submitting a PR.
+
+## License
+
+MIT

package/commands/init.md

@@ -0,0 +1,231 @@
+---
+name: myco-init
+description: Initialize Myco in the current project — sets up vault, config, and intelligence backend
+---
+
+# Initialize Myco
+
+Set up Myco for this project. Guide the user through:
+
+## Step 0: Detect vault location
+
+The vault defaults to `.myco/` in the project root — the team's intelligence lives with the code and is committed to git.
+
+Check whether `MYCO_VAULT_DIR` is set as an override:
+
+- Check the process environment for `MYCO_VAULT_DIR`
+- Also check `.claude/settings.json` under the `env` key for `MYCO_VAULT_DIR`
+- If found and non-empty, use that path instead — **do not ask the user where to put the vault**
+- If not found, use `.myco/` in the project root (the default)
+
+The `MYCO_VAULT_DIR` override is for public repos or cases where the vault should be kept separate from the codebase. For most private projects, the default is correct.
+
+Record the **vault path source** for use in the setup summary:
+- `"from MYCO_VAULT_DIR env"` — if the env var override was set
+- `"default (.myco/)"` — project-local vault (recommended for private repos)
+
+## Step 1: Create vault directory
+
+Create the vault directory (at the resolved path from Step 0) with subdirectories:
+`sessions`, `plans`, `memories`, `artifacts`, `team`, `buffer`, `logs`
+
+Also create a `_dashboard.md` file in the vault root with the following Dataview-powered content:
+
+```markdown
+# Myco Vault
+
+## Active Plans
+\`\`\`dataview
+TABLE status, tags FROM #type/plan
+WHERE status = "active" OR status = "in_progress"
+SORT created DESC
+\`\`\`
+
+## Recent Sessions
+\`\`\`dataview
+TABLE user, started, tools_used FROM #type/session
+SORT started DESC LIMIT 10
+\`\`\`
+
+## Recent Memories
+\`\`\`dataview
+TABLE observation_type AS "Type", created FROM #type/memory
+SORT created DESC LIMIT 15
+\`\`\`
+
+## Memories by Type
+\`\`\`dataview
+TABLE WITHOUT ID observation_type AS "Type", length(rows) AS "Count"
+FROM #type/memory GROUP BY observation_type
+SORT length(rows) DESC
+\`\`\`
+
+## Gotchas
+\`\`\`dataview
+LIST FROM #memory/gotcha SORT created DESC LIMIT 10
+\`\`\`
+```
+
+This dashboard requires the Dataview community plugin in Obsidian. Without it, the code blocks are visible but still readable as plain markdown.
+
+## Step 2: Choose intelligence backend
+
+Configure LLM and embedding providers independently:
+
+### LLM provider
+
+Ask the user to choose an LLM provider:
+
+- **Ollama** — detect at `http://localhost:11434/api/tags`, list available models
+- **LM Studio** — detect at `http://localhost:1234/v1/models`, list available models
+- **Anthropic** — uses existing `ANTHROPIC_API_KEY`, verify it's set
+
+Recommended summarization models by hardware tier:
+
+| Tier | Models | RAM | Notes |
+|------|--------|-----|-------|
+| **High** (best quality) | `gpt-oss` (~20B), `gemma3:27b`, `qwen3.5:14b` | 16GB+ | Best observation extraction and structured JSON output |
+| **Mid** (good balance) | `qwen3.5:8b`, `gemma3:12b` | 8GB+ | Good quality, reasonable speed |
+| **Light** (resource constrained) | `gemma3:4b`, `qwen3.5:4b` | 4GB+ | Faster, may miss nuanced observations |
+
+If the user already has a model loaded, prefer using what they have — any instruction-tuned model that handles JSON output well will work. The model only needs to produce structured JSON (observation extraction) and short text (summaries, titles).
+
+For the selected provider, list available models and let the user choose. Also set:
+- `context_window` (default 8192) — only for local providers, not Anthropic
+- `max_tokens` (default 1024)
+
+If the recommended model isn't available, offer to pull it:
+- **Ollama**: `ollama pull gpt-oss` (pulls latest tag automatically)
+- **LM Studio**: `lms get openai/gpt-oss-20b` (uses `owner/model` format)
+
+Ask the user before pulling — models can be large (hundreds of MB to several GB).
+
+### Embedding provider
+
+Ask the user to choose an embedding provider. **Anthropic is not an option here** — it doesn't support embeddings.
+
+- **Ollama** — detect at `http://localhost:11434/api/tags`, list available models, recommend `bge-m3` or `nomic-embed-text`. Ollama is the recommended provider for embeddings.
+- **LM Studio** — possible but not recommended for embeddings. LM Studio is better suited for LLM/summarization work.
+
+For the selected provider, list available models and let the user choose.
+
+If the recommended embedding model isn't installed, offer to pull it — embedding models are typically small (~300-700MB):
+- **Ollama**: `ollama pull bge-m3`
+
+## Step 3: Team / solo setup
+
+Ask whether this is a team or solo project:
+
+- **Solo** — vault stays local, not tracked by git
+- **Team** — set up git tracking for the vault directory, ask for username
+
+If `MYCO_VAULT_DIR` is set in the environment, also offer:
+- **Use MYCO_VAULT_DIR from env** — treat the env-specified vault as a shared/external vault managed outside this repo; skip git tracking
+
+## Step 4: Write `myco.yaml`
+
+Write a `version: 2` config file with chosen settings. **All configurable values must be explicit** — no hidden schema defaults. Example output:
+
+```yaml
+version: 2
+
+intelligence:
+  llm:
+    provider: ollama
+    model: gpt-oss
+    base_url: http://localhost:11434
+    context_window: 8192
+    max_tokens: 1024
+  embedding:
+    provider: ollama
+    model: bge-m3
+    base_url: http://localhost:11434
+
+daemon:
+  log_level: info
+  grace_period: 30
+  max_log_size: 5242880
+
+capture:
+  transcript_paths: []
+  artifact_watch:
+    - .claude/plans/
+    - .cursor/plans/
+  artifact_extensions:
+    - .md
+  buffer_max_events: 500
+
+context:
+  max_tokens: 1200
+  layers:
+    plans: 200
+    sessions: 500
+    memories: 300
+    team: 200
+
+team:
+  enabled: false
+  user: ""
+  sync: git
+```
+
+Substitute the user's chosen providers, models, and base URLs. Set `team.enabled`, `team.user`, and `team.sync` based on Step 3.
+
+## Step 5: Write vault `.gitignore`
+
+Create a `.gitignore` inside the `.myco/` vault directory to exclude runtime artifacts while committing the knowledge:
+
+```
+# Runtime — rebuilt on daemon startup
+index.db
+index.db-wal
+index.db-shm
+vectors.db
+
+# Daemon state — per-machine, ephemeral
+daemon.json
+buffer/
+logs/
+
+# Obsidian — per-user workspace config
+.obsidian/
+```
+
+Everything else is committed: `myco.yaml`, `sessions/`, `memories/`, `plans/`, `artifacts/`, `team/`, `lineage.json`, `_dashboard.md`. This is the project's institutional memory — it travels with the code.
+
+## Step 6: Vault discovery and MCP
+
+The default `.myco/` vault location requires no configuration — the vault resolver finds it automatically in the project root.
+
+### If the user chose an external vault (MYCO_VAULT_DIR override)
+
+Set `MYCO_VAULT_DIR` in the agent's settings so hooks and the MCP server can find the vault:
+
+**Claude Code** — write to `.claude/settings.json`:
+```json
+{ "env": { "MYCO_VAULT_DIR": "<external vault path>" } }
+```
+
+**Cursor / VS Code** — instruct the user to set `MYCO_VAULT_DIR` in their shell profile (`~/.zshrc`, `~/.bashrc`), or set it in the MCP server's env block if configuring manually.
+
+### MCP server registration
+
+All three agents (Claude Code, Cursor, VS Code Copilot) auto-discover the MCP server from the plugin manifest when installed via the marketplace. No manual `.mcp.json` editing is needed.
+
+## Step 7: Setup summary
+
+After setup, display a summary:
+
+| Setting | Value |
+|---------|-------|
+| Vault path | `<resolved path>` (`<vault path source>`) |
+| LLM provider | `<provider>` / `<model>` |
+| Embedding provider | `<provider>` / `<model>` |
+| Context window | `<context_window>` |
+| Team mode | `<enabled/disabled>` |
+
+Then confirm everything is working:
+1. Verify the LLM provider is reachable (call `isAvailable()`)
+2. Verify the embedding provider is reachable (call `isAvailable()`)
+3. Run a test embedding to confirm dimensions
+4. Report success or issues found

package/commands/setup-llm.md

@@ -0,0 +1,89 @@
+---
+name: myco-setup-llm
+description: Configure or change the intelligence backend (Ollama, LM Studio, or Anthropic)
+---
+
+# LLM Backend Setup
+
+Guide the user through configuring their intelligence backend. This command can be run at any time to change providers or models.
+
+## Prerequisites
+
+Read the existing `myco.yaml` from the vault directory to show current settings before making changes.
+
+## Step 1: Detect available providers
+
+Check which providers are reachable:
+
+- **Ollama** — fetch `http://localhost:11434/api/tags`, list model names
+- **LM Studio** — fetch `http://localhost:1234/v1/models`, list model names
+- **Anthropic** — check if `ANTHROPIC_API_KEY` is set in the environment
+
+Report which are available and which are not.
+
+## Step 2: Choose LLM provider
+
+Ask the user to select from available providers:
+
+- **Ollama** — list available models
+- **LM Studio** — list available models
+- **Anthropic** — verify API key works, default model `claude-haiku-4-5-20251001`
+
+Recommended summarization models by hardware tier:
+
+| Tier | Models | RAM |
+|------|--------|-----|
+| **High** | `gpt-oss` (~20B), `gemma3:27b`, `qwen3.5:14b` | 16GB+ |
+| **Mid** | `qwen3.5:8b`, `gemma3:12b` | 8GB+ |
+| **Light** | `gemma3:4b`, `qwen3.5:4b` | 4GB+ |
+
+Any instruction-tuned model that handles JSON output works. Prefer what the user already has loaded.
+
+For local providers (Ollama, LM Studio), also configure:
+- `context_window` — ask or accept default of 8192
+- `max_tokens` — ask or accept default of 1024
+
+If the chosen model isn't installed, offer to pull it:
+- **Ollama**: `ollama pull gpt-oss` (pulls latest tag automatically)
+- **LM Studio**: `lms get openai/gpt-oss-20b` (uses `owner/model` format)
+
+These settings do not apply to Anthropic (API-managed).
+
+## Step 3: Choose embedding provider
+
+Ask the user to select from available providers — **Anthropic is not an option** (it doesn't support embeddings):
+
+- **Ollama** (recommended for embeddings) — list available models, recommend **`bge-m3`** or `nomic-embed-text`
+- **LM Studio** — possible but not recommended for embeddings; better suited for LLM work
+
+If the embedding model isn't installed: `ollama pull bge-m3`
+
+**Important:** If the user changes the embedding model, the vector index must be rebuilt. Warn them:
+> "Changing the embedding model will require a full rebuild of the vector index. Run `node dist/src/cli.js rebuild` after this change."
+
+## Step 4: Update `myco.yaml`
+
+Write both `intelligence.llm` and `intelligence.embedding` sections with all values explicit:
+
+```yaml
+intelligence:
+  llm:
+    provider: ollama
+    model: gpt-oss
+    base_url: http://localhost:11434
+    context_window: 8192
+    max_tokens: 1024
+  embedding:
+    provider: ollama
+    model: bge-m3
+    base_url: http://localhost:11434
+```
+
+If migrating from a v1 config (has `backend: local/cloud` structure), bump `version` to `2` and rewrite the entire intelligence section. The loader auto-maps `provider: haiku` to `anthropic`.
+
+## Step 5: Verify and restart
+
+1. Test the LLM provider with a simple prompt
+2. Test the embedding provider with a test embedding
+3. Restart the daemon to pick up the new config: `node dist/src/cli.js restart`
+4. Report success or issues found