kodelyth-ecc 1.5.9 → 1.7.0

package/docs/evolve.md

@@ -0,0 +1,303 @@
+# Self-evolving memory
+
+> Phase 3.4 of the Devil Roadmap. Closes the learning loop on the BM25 memory system. Repeated memory hits become draft skills. Repeated routing misses become proposed routing-rule additions. Nothing is ever auto-applied.
+
+---
+
+## Why this exists
+
+ECC already has:
+
+- A BM25 memory store (`scripts/memory/store.js`)
+- An auto-recall hook that surfaces relevant memories on every `UserPromptSubmit`
+
+What it didn't have, until 3.4: a way for those signals to feed back into the toolkit's own structure. If the same memory keeps getting surfaced across sessions, that memory is doing real work — it should graduate to a `SKILL.md`. If users keep submitting prompts that match no memory at all, that's a routing gap — the routing rule should grow.
+
+The 3.4 surface formalizes both loops while preserving the **never auto-commit** rule.
+
+---
+
+## Two signal streams
+
+### 1. Memory reuse (→ skill-upgrade proposals)
+
+Every time `auto-recall.js` surfaces a memory to the user, it bumps a counter:
+
+```jsonc
+// ~/.kodelyth/evolve/reuse.json
+{
+  "byMemory": {
+    "<memoryId>": {
+      "count": 7,
+      "sessions": ["s1", "s2", "s3", ...],
+      "projects": ["/path/to/proj-a", "/path/to/proj-b"],
+      "firstSurfaced": "2026-04-30T...",
+      "lastSurfaced":  "2026-05-10T..."
+    }
+  },
+  "lastUpdated": "2026-05-10T..."
+}
+```
+
+Counter semantics:
+
+- **Per-memory, per-session**: surfacing the same memory ten times in one session counts ONCE. Matches the existing "never re-surface the same memory twice in a session" rule of `auto-recall.js`.
+- **Cross-session**: each fresh session bumps the count by exactly one.
+- **Idempotent**: replaying a session does not double-count.
+
+Default threshold: count ≥ 3 AND sessions ≥ 2 → eligible for skill-upgrade proposal.
+
+### 2. Routing misses (→ routing-addition proposals)
+
+When `shouldRecall(prompt)` is true (substantive prompt, ≥12 chars, ≥2 meaningful tokens, not a slash command) AND BM25 recall returns zero matches, the prompt is logged:
+
+```jsonl
+// ~/.kodelyth/evolve/routing-misses.jsonl  (append-only)
+{"hash":"abc...","prompt":"...","tokens":["..."],"session_id":"...","project":"...","recorded_at":"..."}
+```
+
+Stored prompts are capped at 1000 chars. Top tokens are extracted at write time so analysis is cheap.
+
+Default threshold: cluster count ≥ 3 AND distinct prompts ≥ 2 → eligible for routing-addition proposal.
+
+---
+
+## CLI
+
+### `kodelyth-ecc evolve stats`
+
+Snapshot of recorded signals. No proposals generated.
+
+```
+Kodelyth ECC — self-evolving memory stats
+  reuse:
+    memories tracked: 14
+    total surfaces:   42
+    last updated:     2026-05-10T17:23:00.000Z
+    top reused:
+      • efe17d650917e445  count=7  sessions=5
+      • a91ce2034d8b1234  count=5  sessions=4
+  routing misses:
+    total:            18
+    unique prompts:   11
+    top clusters:
+      • count=4  tokens=[feature, flag, gradual, rollout]
+      • count=3  tokens=[migration, postgres, downtime, zero]
+```
+
+### `kodelyth-ecc evolve analyze`
+
+Apply thresholds and write proposals. Idempotent — same evidence produces the same proposal ID, so re-running never duplicates.
+
+| Flag | Default | Effect |
+|---|---|---|
+| `--reuse-min N` | 3 | minimum total surface count |
+| `--reuse-min-sessions N` | 2 | minimum distinct sessions |
+| `--miss-min N` | 3 | minimum miss-cluster total |
+| `--miss-min-distinct N` | 2 | minimum distinct prompts in cluster |
+| `--json` | off | full report instead of pretty summary |
+
+### `kodelyth-ecc evolve list [--status pending|accepted|rejected|applied]`
+
+Show proposals. Filter by status. Pretty output uses ⏸ ✓ ✗ ★ marks for the four states.
+
+### `kodelyth-ecc evolve show <id>`
+
+Print the full proposed file content + evidence. **Always preview before accepting.**
+
+### `kodelyth-ecc evolve accept <id> [--root DIR] [--overwrite]`
+
+Write the proposed `diff` to its `target_path` under `--root`. Refuses to overwrite an existing file unless `--overwrite` is explicit. Marks the proposal `accepted` with the absolute `applied_path` written to the audit trail.
+
+**The CLI does not stage, does not commit, does not push.** Review the draft, edit, commit by hand.
+
+### `kodelyth-ecc evolve reject <id> [--note "..."]`
+
+Mark a proposal `rejected`. The optional `--note` is preserved in the audit trail for future reference.
+
+---
+
+## Proposal anatomy
+
+Both proposal kinds share a structure:
+
+```jsonc
+{
+  "id": "skill-2537cb787a",          // deterministic over evidence
+  "type": "skill-upgrade",            // or "routing-addition"
+  "evidence": {
+    "memoryId": "efe17d650917e445",
+    "reuseCount": 7,
+    "sessions": ["s1", "s2", "s3", "s4", "s5"],
+    "firstSurfaced": "...",
+    "lastSurfaced": "..."
+  },
+  "proposal": {
+    "kind": "create-skill",                                            // or "add-routing-entry"
+    "target_path": "skills/<slug>/SKILL.md",                           // for skill-upgrade
+    "diff": "<full markdown content>",
+    "rationale": "Memory '...' surfaced 7x across 5 sessions ..."
+  },
+  "status": "pending",                // pending | accepted | rejected | applied
+  "created_at": "...",
+  "timestamp": "...",
+  "applied_path": null                // set on accept
+}
+```
+
+### Skill-upgrade diff (sample)
+
+```markdown
+---
+name: <slug-from-problem>
+description: <problem text> (auto-derived from memory <id> after repeated reuse)
+origin: kodelyth-evolve
+language: typescript
+tags:
+  - <memory tags>
+---
+
+# Skill: <slug>
+
+> **Auto-derived draft.** Generated by `kodelyth-ecc evolve` after this memory
+> was surfaced repeatedly across multiple sessions. Review, refine, and rename
+> before committing.
+
+## Problem
+<memory.problem>
+
+## Approach
+<memory.approach>
+
+## Gotchas
+<memory.gotchas if any>
+
+## When to invoke
+_Replace this section with explicit trigger conditions._
+
+## Origin
+- Memory id: `<id>`
+- Captured at: <timestamp>
+- Auto-promoted by Phase 3.4 self-evolving memory.
+```
+
+### Routing-addition diff (sample)
+
+```markdown
+<!-- proposed addition to rules/common/agent-intent-routing.md -->
+<!-- review by hand, decide on tier + agent, then merge -->
+
+### TODO-agent — covers prompts about <token>, <token>, <token>
+
+Trigger if the user mentions `<t1>`, `<t2>`, `<t3>`.
+
+| Signal | Real human phrasing |
+|---|---|
+| repeated unrouted prompt cluster | <tokens> |
+
+**Origin:** Phase 3.4 self-evolving memory — N prompts in this cluster were
+submitted with no memory match and (presumably) no specialist routing.
+
+Recent samples:
+  - "<sample 1>"
+  - "<sample 2>"
+  - "<sample 3>"
+
+_(Pick the right tier in `rules/common/agent-intent-routing.md` before merging.
+Do NOT commit this block as-is — replace `TODO-agent` with the real agent name
+and slot under the correct priority tier.)_
+```
+
+The `TODO-agent` placeholder is intentional. Even if you accept and commit verbatim, the rule won't route any real traffic — it's a no-op until you fill in the agent name.
+
+---
+
+## Storage layout
+
+```
+~/.kodelyth/evolve/                        ← override with $KODELYTH_EVOLVE_DIR
+├── reuse.json                             ← per-memory reuse counters
+├── routing-misses.jsonl                   ← append-only miss log
+└── proposals.jsonl                        ← append-only proposal events
+```
+
+`proposals.jsonl` is append-only. Every state transition is a new event. Reading collapses to "latest state per id" while preserving the full history for audit.
+
+---
+
+## Worked example
+
+```bash
+# 1) Use ECC normally for a few weeks. The auto-recall hook records signals.
+# 2) Eventually run:
+$ npx kodelyth-ecc evolve stats
+... shows current signal volume ...
+
+# 3) Generate proposals.
+$ npx kodelyth-ecc evolve analyze
+✓ analyzed signals
+  reuse entries scanned:  14
+  miss entries scanned:   11
+  proposals generated:    3
+  new proposals (added):  3
+
+  Run 'kodelyth-ecc evolve list' to review.
+
+# 4) See what's pending.
+$ npx kodelyth-ecc evolve list
+Kodelyth ECC — self-evolving memory proposals (3)
+  ⏸ [pending] skill-2537cb787a  skill-upgrade
+     target: skills/tailwind-v4-arbitrary-values/SKILL.md
+     why:    Memory '...' surfaced 7x across 5 sessions ...
+  ⏸ [pending] route-13d976a554  routing-addition
+     target: rules/common/agent-intent-routing.md
+     why:    4 substantive prompts (4 distinct) clustered on tokens [...]
+
+# 5) Inspect the skill draft.
+$ npx kodelyth-ecc evolve show skill-2537cb787a
+... full markdown + evidence ...
+
+# 6) Accept it. Writes to disk. NEVER commits.
+$ npx kodelyth-ecc evolve accept skill-2537cb787a
+✓ accepted skill-2537cb787a
+  draft written: /path/to/repo/skills/tailwind-v4-arbitrary-values/SKILL.md
+
+  Review the draft. When you're happy with it, commit it.
+
+# 7) Reject the routing one — already covered.
+$ npx kodelyth-ecc evolve reject route-13d976a554 --note "covered by debug-detective"
+✗ rejected route-13d976a554 (note: covered by debug-detective)
+```
+
+---
+
+## Hard rules
+
+1. **NEVER auto-apply.** `accept` writes a draft. The user reviews, edits, commits.
+2. **NEVER overwrite without `--overwrite`.** Even on accept of a stale proposal.
+3. **NEVER block the recall hook.** All evolve recording is wrapped in try/catch and lazy-required.
+4. **NEVER auto-route a `TODO-agent` proposal.** The placeholder is intentional.
+5. **Idempotent IDs.** Stable evidence → stable proposal ID. Re-running `analyze` never duplicates.
+6. **Append-only proposal log.** Every state change is a new event. Full audit trail preserved.
+
+---
+
+## Composition with other phases
+
+| Pair | Effect |
+|---|---|
+| BM25 memory store | Source of reuse signals. |
+| `/memory remember` | Manually captured memories that get reused → skill proposals. |
+| `rules/common/agent-intent-routing.md` | Direct target for routing-addition proposals. |
+| Phase 2.7 swarm | Repeated swarm tasks reusing the same memories → those memories become skills the swarm picker can choose automatically. |
+| Phase 2.8 replay | Replay bundles re-trigger reuse signals when the same memory is surfaced again. |
+| Phase 2.10 token-budget hook | Promoting memories → skills means cheaper recalls. |
+
+---
+
+## See also
+
+- `skills/self-evolving-memory/SKILL.md` — explicit-invocation skill
+- `commands/memory-evolve.md` — `/memory-evolve` slash command
+- `scripts/evolve/{stats,analyze,proposals}.js` — pure-function implementation
+- `hooks/memory/auto-recall.js` — signal capture (Phase 3.4 augmentation)

package/docs/mcp-clients.md

@@ -0,0 +1,167 @@
+# Kodelyth ECC — MCP Client Mode
+
+The other half of the MCP story. While `npx kodelyth-ecc mcp` (Phase 2.1) **serves** ECC to any MCP-compatible client, MCP client mode lets ECC **consume** any external MCP server — Stripe, GitHub, Postgres, Redis, Brave, Filesystem, Shopify, Sentry, anything.
+
+> **Phase 2.5 of the [Devil Roadmap](../README.md).** This makes ECC the MCP **hub**, not just a node. Local-only registry. Zero telemetry. Same SDK as the server side.
+
+---
+
+## Quick start
+
+### 1. Register an external MCP server
+
+```bash
+# Public servers (no env vars needed)
+npx kodelyth-ecc mcp-add brave -- npx -y @modelcontextprotocol/server-brave-search
+npx kodelyth-ecc mcp-add filesystem -- npx -y @modelcontextprotocol/server-filesystem /Users/me/notes
+
+# Servers that need credentials
+npx kodelyth-ecc mcp-add github \
+  --env GITHUB_PERSONAL_ACCESS_TOKEN=ghp_... \
+  --desc "ECC project ops on github" \
+  -- npx -y @modelcontextprotocol/server-github
+
+npx kodelyth-ecc mcp-add postgres \
+  --env DB_URL=postgres://localhost/myapp \
+  -- npx -y @modelcontextprotocol/server-postgres
+
+npx kodelyth-ecc mcp-add stripe \
+  --env STRIPE_API_KEY=sk_... \
+  -- npx -y @stripe/mcp
+```
+
+The registry is stored at `~/.kodelyth/mcp-clients.json` (override with `KODELYTH_MCP_CLIENT_DIR`).
+
+### 2. Inspect a registered server
+
+```bash
+npx kodelyth-ecc mcp-list                       # all registered
+npx kodelyth-ecc mcp-tools github               # tools the server exposes
+npx kodelyth-ecc mcp-resources filesystem       # resources
+npx kodelyth-ecc mcp-prompts brave              # prompts
+```
+
+### 3. Call a tool
+
+```bash
+# No args:
+npx kodelyth-ecc mcp-call github list_repos
+
+# JSON args:
+npx kodelyth-ecc mcp-call github create_issue \
+  --json '{"owner":"sifxprime","repo":"kodelyth-ecc","title":"hi from ECC"}'
+
+npx kodelyth-ecc mcp-call postgres query \
+  --json '{"sql":"SELECT count(*) FROM users"}'
+```
+
+### 4. Unregister
+
+```bash
+npx kodelyth-ecc mcp-remove github
+```
+
+---
+
+## CLI surface
+
+| Command | Description |
+|---|---|
+| `mcp-add <name> [--env K=V] [--desc "..."] -- <command> [args...]` | Register an external server. |
+| `mcp-list` | List registered servers. |
+| `mcp-remove <name>` | Unregister. |
+| `mcp-tools <name>` | List tools exposed by the server. |
+| `mcp-resources <name>` | List resources. |
+| `mcp-prompts <name>` | List prompts. |
+| `mcp-call <name> <tool> [--json '{"arg":"value"}']` | Call a tool with JSON arguments. |
+
+The `--` separator before the command is mandatory in `mcp-add` so the registry can disambiguate flags belonging to ECC from flags meant for the external server.
+
+---
+
+## Programmatic use
+
+The same registry powers in-session agent tool calls. Inside an ECC agent or skill, require the client library:
+
+```js
+const client = require('kodelyth-ecc/scripts/mcp/client.js');
+
+// Open a stable connection.
+const session = await client.connect('github');
+const out = await session.client.callTool({
+  name: 'create_issue',
+  arguments: { owner: 'sifxprime', repo: 'kodelyth-ecc', title: 'auto-issue' },
+});
+await session.close();
+
+// Or one-shot:
+const tools = await client.listTools('postgres');
+const stats = await client.callTool('redis', 'set', { key: 'k', value: 'v' });
+```
+
+Every call spawns a fresh stdio subprocess; there's no long-lived process pool. This is intentional — failed servers don't poison subsequent calls, and credentials live only in the per-call env.
+
+---
+
+## Registry shape
+
+```json
+{
+  "servers": {
+    "github": {
+      "name": "github",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env":  { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..." },
+      "description": "ECC project ops on github",
+      "added_at": "2026-05-10T10:48:00.690Z"
+    }
+  }
+}
+```
+
+You can hand-edit the file. Reserved name patterns: alphanumeric, dash, underscore.
+
+---
+
+## Pairing with the rest of ECC
+
+| Pairs with | How |
+|---|---|
+| **Phase 2.1 — MCP server** | The two halves complete each other. ECC serves to any framework AND consumes from any provider. |
+| **Phase 2.10 — prompt-injection-guard** | Tool responses from external MCP servers are scanned for indirect injection on `PostToolUse:mcp__*` (opt in via `KODELYTH_PI_GUARD=warn|block`). |
+| **Phase 2.4 — cost-aware model router** | Tool responses are part of the session token-budget when the safety hook is enabled. |
+| **kodelyth-memory** | Capture interesting tool responses as memories with `kodelyth-ecc remember "..." --approach "..."`. |
+
+---
+
+## Privacy & safety
+
+- **No network egress from this client** — it only spawns subprocesses you registered.
+- **Credentials live in the registry file.** Treat `~/.kodelyth/mcp-clients.json` like a secrets file. `chmod 600` is recommended on shared machines.
+- **External servers can do whatever the user gives them permission to do** — register only servers you trust.
+- **Pair with `prompt-injection-guard`** to scan tool responses for indirect injection before agents act on them.
+
+---
+
+## Troubleshooting
+
+**"Kodelyth MCP client requires `@modelcontextprotocol/sdk`"** — run `npm install @modelcontextprotocol/sdk` once, or rerun via `npx -y kodelyth-ecc ...`.
+
+**"MCP server X is not registered"** — `mcp-list` shows nothing because the registry lives at `~/.kodelyth/mcp-clients.json` (or `$KODELYTH_MCP_CLIENT_DIR`). Re-run `mcp-add`.
+
+**Server hangs on connect** — the external server probably needs env vars you didn't pass. Re-add with `--env KEY=VAL`.
+
+**Tool call returns `isError: true`** — the external server rejected the call. Inspect the `content[0].text` for the underlying error message; it's typed exactly as the spec.
+
+---
+
+## Roadmap interactions
+
+- **Phase 2.6 — sandbox layer** will wrap external MCP servers in Docker/firejail isolation by default.
+- **Phase 2.3 — local dashboard** will show live MCP traffic per registered server (count, latency, errors).
+- **Phase 2.9 — SLSA/SBOM** will publish provenance for the ECC server side and let `supply-chain-auditor` verify external server packages.
+
+---
+
+Built into [Kodelyth ECC](../README.md). MIT licensed. PRs welcome.

package/docs/mcp.md

@@ -0,0 +1,178 @@
+# Kodelyth ECC — MCP Server
+
+The Kodelyth ECC MCP (Model Context Protocol) server is the **universal adapter** that lets any MCP-compatible client consume the full ECC stack: 70 agents, 194 skills, 97 commands, 14 rules, 3 power bundles, and the local BM25 self-learning memory.
+
+If you've ever wished LangGraph, AutoGen, CrewAI, OpenAI Agents SDK, Claude Desktop, or any other agent framework could speak ECC natively — this is that bridge.
+
+Local-only, zero telemetry, stdio transport.
+
+---
+
+## Quick start
+
+### 1. Run the server
+
+```bash
+# From npm (recommended):
+npx kodelyth-ecc mcp
+
+# From this repo:
+node scripts/mcp/server.js
+```
+
+The server speaks JSON-RPC over **stdio**. It stays alive until stdin closes.
+
+You'll see one stderr banner on boot, e.g.:
+
+```
+[kodelyth-mcp] ready · 1.7.0 · 16 tools · 6 prompts · 365 resources
+```
+
+### 2. Wire it into your MCP client
+
+#### Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS)
+
+```json
+{
+  "mcpServers": {
+    "kodelyth-ecc": {
+      "command": "npx",
+      "args": ["-y", "kodelyth-ecc", "mcp"]
+    }
+  }
+}
+```
+
+#### Cursor / Windsurf / any MCP-aware IDE
+
+Use the same `command` + `args` pattern under whatever the IDE's MCP server config key is.
+
+#### Programmatic clients (LangGraph, AutoGen, CrewAI, OpenAI Agents SDK, custom)
+
+Spawn the server as a subprocess and connect via the official MCP client SDK for your language. The transport is **stdio JSON-RPC** — every spec-compliant client supports it.
+
+---
+
+## What it exposes
+
+### Tools (16)
+
+| Name | Purpose |
+|---|---|
+| `route_intent` | Suggest the best ECC agent for a user message via token-overlap. Pair with the `routing-rule` prompt for full tier-based routing. |
+| `list_agents` | List every ECC agent (name, description, relpath). |
+| `list_skills` | List every ECC skill. |
+| `list_commands` | List every slash command. |
+| `list_rules` | List every rule file in `rules/common/`. |
+| `list_bundles` | List the power bundles (indie-hacker, red-team, enterprise). |
+| `get_agent` | Fetch the full markdown body of one agent. |
+| `get_skill` | Fetch the full markdown body of one skill. |
+| `get_command` | Fetch the full markdown body of one slash command (with or without leading `/`). |
+| `get_rule` | Fetch a rule file body. |
+| `get_bundle` | Fetch a bundle cheat sheet body. |
+| `recall_memory` | BM25 search across the local Kodelyth memory store. |
+| `capture_memory` | Append a new memory entry (problem + approach + tags). |
+| `memory_stats` | Summary of the local memory store. |
+| `catalog_stats` | Summary of how many agents/skills/commands/rules/bundles are loaded. |
+| `audit_skill_match` | Suggest skills whose description/body overlap a task — useful for deciding which skills to attach as context. |
+
+All tool results follow the MCP `{ content: [{ type: 'text', text: ... }], isError? }` shape. Most return JSON-encoded payloads inside the text channel.
+
+### Prompts (6)
+
+Prompts let clients summon canonical ECC context blocks by name, no tool call needed.
+
+| Name | Returns |
+|---|---|
+| `routing-rule` | The full ECC intent routing rule (10-tier priority system). |
+| `agents-overview` | Compact list of all 70 agents with one-line descriptions. |
+| `skills-overview` | Compact list of all 194 skills. |
+| `commands-overview` | Compact list of all 97 slash commands. |
+| `handoff-chains` | The `agent-handoff` skill body — standard multi-agent chains for new feature, bug fix, refactor, incident, etc. |
+| `devil-mode` | The `/devil-mode` parallel command — fires the adversarial red-team crew. |
+
+### Resources (365)
+
+Every agent, skill, command, rule, and bundle is also addressable as an MCP resource:
+
+```
+kodelyth://agents/<name>
+kodelyth://skills/<name>
+kodelyth://commands/<name>
+kodelyth://rules/<name>
+kodelyth://bundles/<name>
+```
+
+All resources are `text/markdown`. Use `resources/list` to discover, `resources/read` to fetch.
+
+---
+
+## Example session
+
+```jsonc
+// → client
+{ "jsonrpc": "2.0", "id": 1, "method": "initialize",
+  "params": { "protocolVersion": "2024-11-05", "capabilities": {},
+              "clientInfo": { "name": "my-client", "version": "0.1.0" } } }
+
+// ← server
+{ "jsonrpc": "2.0", "id": 1, "result": {
+  "protocolVersion": "2024-11-05",
+  "capabilities": { "tools": {}, "resources": {}, "prompts": {} },
+  "serverInfo": { "name": "kodelyth-ecc", "version": "1.7.0" } } }
+
+// → client
+{ "jsonrpc": "2.0", "id": 2, "method": "tools/call",
+  "params": { "name": "route_intent",
+              "arguments": { "message": "production is down and i don't know why",
+                             "top_k": 3 } } }
+
+// ← server (paraphrased)
+{ "result": { "content": [{ "type": "text", "text":
+  "{ \"suggestions\": [
+       { \"agent\": \"incident-commander\", ... },
+       { \"agent\": \"debug-detective\",    ... },
+       { \"agent\": \"silent-failure-hunter\", ... }
+     ] }" }] } }
+```
+
+---
+
+## Design notes
+
+- **Pure file reads + memory passthrough.** The server adds no LLM calls of its own. It surfaces ECC context; your client's model decides what to do with it.
+- **No telemetry, no network egress.** stdio only. Local memory only. Reads from this repo's checked-in markdown.
+- **Lazy SDK load.** The MCP SDK is an `optionalDependency` so installs work without it; the `mcp` subcommand prints a friendly install hint if missing.
+- **Cached catalog.** Agent/skill/command lists are cached in-process after first read for sub-millisecond subsequent calls.
+- **Memory store is project-aware.** `recall_memory` accepts an optional `project_root` to scope BM25 results to memories captured against that project, falling back to global memories if scoped results are sparse.
+
+---
+
+## Privacy & safety
+
+- The server only reads files under this package and the local memory directory (default `~/.kodelyth/memory/`, override via `KODELYTH_MEMORY_DIR`).
+- It writes only when the client invokes `capture_memory`.
+- No network calls. No analytics. No phone-home.
+- The server never executes arbitrary commands or code. Tools that surface code (`get_agent`, etc.) return markdown documentation, not executable instructions.
+
+---
+
+## Troubleshooting
+
+**"Kodelyth MCP server requires `@modelcontextprotocol/sdk`"** — run `npm install @modelcontextprotocol/sdk` once, or rerun via `npx -y kodelyth-ecc mcp` to let npm fetch optional deps.
+
+**Empty results from `recall_memory` on a fresh memory store** — BM25 needs a few documents before IDF scores rise above the default `minScore` floor. Capture 2-3 memories first.
+
+**Resources missing in your client UI** — some MCP clients render only tools and prompts. Resources are still queryable via `resources/list`.
+
+---
+
+## Roadmap interactions
+
+- **Phase 2.5 — MCP client mode** will add the inverse: ECC agents consuming external MCP servers (Stripe, GitHub, Postgres, Brave, etc.) — making ECC the MCP **hub**, not just a node.
+- **Phase 2.3 — local dashboard** will visualize live MCP traffic so you can see which tools/prompts/resources clients hit, in real time.
+- **Phase 2.10 — prompt-injection guardrail** will sit in front of MCP responses to scrub jailbreak patterns before they reach client models.
+
+---
+
+Built into [Kodelyth ECC](../README.md). MIT licensed. PRs welcome.