Leyline

Meta-harness for Kiro — agent orchestration, persistent memory, task coordination, and self-learning capabilities.

Leyline is invisible infrastructure that connects agents, memory, and tools — purpose-built for Kiro's native architecture. It runs as an MCP server that Kiro connects to, providing 124 tools for memory persistence, agent coordination, task management, autonomous execution, goal planning, and more.

Quick Start

npx @focuslabs/leyline init    # Generate .kiro/ structure + lifecycle hooks

CLI Commands

leyline init              Generate .kiro/ structure with Leyline MCP config + hooks
leyline mcp start         Start the Leyline MCP server (stdio transport)
leyline status            Show current Leyline system status (including vector index)
leyline doctor            Check Leyline installation health (including vector health)
leyline session status    Show context archive status
leyline session save      Save current session context
leyline session restore   Restore archived context
leyline session full-save   Save complete system state snapshot
leyline session full-restore  Restore from state snapshot
leyline session list      List available session snapshots
leyline session diff      Compare two session snapshots
leyline autopilot status  Show autopilot state and iteration stats
leyline autopilot enable  Enable autopilot with configuration
leyline autopilot disable Disable autopilot
leyline goal create       Create a new goal with success criteria
leyline goal status       Show goal progress and drift
leyline goal list         List all goals with status
leyline adr create        Create a new Architecture Decision Record
leyline adr list          List all ADRs with status filter
leyline adr status        Show specific ADR details
leyline plugin install    Install a plugin (npm package or local path)
leyline plugin list       List installed plugins
leyline plugin remove     Remove an installed plugin
leyline plugin create     Scaffold a new plugin project
leyline plugin enable     Enable a disabled plugin
leyline plugin disable    Disable a plugin without removing
leyline worker status     Show worker system status
leyline worker list       List all workers with metrics
leyline worker run        Run a specific worker immediately
leyline workflow <cmd>    Workflow management (create, run, status, list, pause, resume, cancel)
leyline trace <cmd>       Trace management (list, get, search)
leyline metrics [name]    Show metrics summary or specific metric
leyline --help            Show help
leyline --version         Show version

Architecture

User → npx leyline init → generates .kiro/ structure
                                ├── settings/mcp.json (registers Leyline MCP server)
                                ├── agents/ (orchestrator, coder, tester, reviewer)
                                ├── skills/ (memory-management, task-coordination)
                                ├── hooks/ (leyline-lifecycle.json — 5 lifecycle hooks)
                                └── steering/ (leyline behavioral rules)

User → Kiro (IDE/CLI) → connects to Leyline MCP server → 124 tools:
                              ├── Memory: store, search, list, retrieve, reindex, similar, vector_status
                              ├── Memory Intelligence: bridge_import, bridge_status, smart_search, graph_status, graph_neighbors, graph_rank
                              ├── Agent: spawn, list, status
                              ├── Task: create, assign, status, list
                              ├── Swarm: init, status, stop, send, receive, route, propose, vote
                              ├── Neural: learn, suggest, train, status
                              ├── Intelligence: trajectory_start, trajectory_step, trajectory_end, pattern_search, pipeline_status
                              ├── Context: session_save, session_restore, session_status, session_archive, session_prune
                              ├── Session: full_save, full_restore, list, diff
                              ├── Autopilot: enable, disable, status, config, predict, progress, learn, history, log, reset
                              ├── Goals: create, plan, status, list, complete, research, horizon_track, horizon_status
                              ├── Skills: candidates, promote, status, generate
                              ├── Hooks: register, list, emit, stats
                              ├── Workers: run, list, status, start, stop
                              ├── Plugins: list, install, remove, status
                              ├── Routing: route, record, cost, config, list, status
                              ├── Cost: budget_set, budget_status, alert_list, optimize
                              ├── Security: scan, audit, policy, status
                              ├── Workflows: create, run, status, list, pause, resume, cancel, delete, step_status, template
                              ├── Observability: trace_list, trace_get, trace_search, metrics_summary, metrics_get, observability_status
                              ├── ADR: create, list, get, update, search
                              ├── Federation: init, join, peers, send, status, trust (stubs)
                              └── System: status, health

User Journey

flowchart LR
    Init([npx leyline init]) --> |generates .kiro/| Structure[Project Structure\nagents + skills + hooks + steering]
    Structure --> Connect[Kiro connects\nto MCP server]
    Connect --> Use{Use Leyline}

    Use --> |store/search| Memory([Memory\nPersistent Knowledge])
    Use --> |create/assign| Tasks([Tasks\nWork Tracking])
    Use --> |enable| Autopilot([Autopilot\nAutonomous Loops])
    Use --> |create/plan| Goals([Goals\nGOAP Decomposition])

    Memory --> Learn[System Learns\nIntelligence Pipeline]
    Tasks --> Learn
    Autopilot --> Learn
    Goals --> Learn

    Learn --> Patterns[Patterns Extracted]
    Patterns --> |confidence ≥ 0.9| Skills([Skills Auto-Generated\n.kiro/skills/learned/])
    Skills --> |next session| Use

Kiro Lifecycle Hooks

Leyline integrates with Kiro's lifecycle hook system via .kiro/hooks/leyline-lifecycle.json (generated by leyline init):

| Hook | Trigger | Purpose | |------|---------|---------| | leyline-session-start | SessionStart | Restore archived context into session | | leyline-memory-bridge | SessionStart | Import Kiro project memory files | | leyline-context-archive | UserPromptSubmit | Proactively archive conversation turns | | leyline-session-end | Stop | Save session state on exit | | leyline-autopilot-learn | PostTaskExec | Record task outcome for learning |

MCP Tools Reference (124 tools)

Memory Tools (4)

| Tool | Description | |------|-------------| | memory_store | Store a key-value pair with namespace and tags | | memory_search | BM25 keyword search (or smart 5-phase retrieval with smart: true) | | memory_list | List all entries, optionally by namespace | | memory_retrieve | Get a specific entry by key |

Vector Search Tools (3)

| Tool | Description | |------|-------------| | memory_reindex | Re-embed all memories into the vector index | | memory_similar | Find entries semantically similar to a given entry | | memory_vector_status | Get vector index health, coverage, and provider info |

Memory Bridge + Smart Retrieval Tools (3)

| Tool | Description | |------|-------------| | memory_bridge_import | Manually trigger memory import from Kiro project files | | memory_bridge_status | Show bridge state (last import, entry count, sources) | | memory_smart_search | Run 5-phase smart retrieval pipeline (expansion, RRF, recency, MMR, round-robin) |

Memory Graph Tools (3)

| Tool | Description | |------|-------------| | memory_graph_status | Graph stats (node count, edge count, top-ranked entries) | | memory_graph_neighbors | Get neighbors of a specific memory entry | | memory_graph_rank | Get PageRank scores for entries (top-N most important) |

Agent Tools (3)

| Tool | Description | |------|-------------| | agent_spawn | Create an agent coordination record | | agent_list | List agents with optional status/type filter | | agent_status | Get details of a specific agent |

Task Tools (4)

| Tool | Description | |------|-------------| | task_create | Create a new task for tracking work | | task_assign | Assign a task to an agent | | task_status | Get or update task status | | task_list | List tasks with optional filters |

Swarm Tools (8)

| Tool | Description | |------|-------------| | swarm_init | Initialize a swarm with topology (hierarchical, mesh, star, ring) | | swarm_status | Get current swarm state (topology, agents, connections) | | swarm_stop | Stop the active swarm | | swarm_send | Send a message from one agent to another (or broadcast) | | swarm_receive | Poll an agent's message inbox | | swarm_route | Auto-assign a task to the best available agent (neural-enhanced) | | swarm_propose | Create a consensus proposal for agents to vote on | | swarm_vote | Cast a vote on an active proposal |

Neural Learning Tools (4)

| Tool | Description | |------|-------------| | neural_learn | Record a task outcome and learn routing patterns from it | | neural_suggest | Get agent routing suggestion based on learned patterns | | neural_train | Batch train on multiple task trajectories | | neural_status | Get neural system statistics and performance metrics |

Intelligence Pipeline Tools (5)

| Tool | Description | |------|-------------| | neural_trajectory_start | Start tracking a task execution trajectory | | neural_trajectory_step | Add an execution step to an active trajectory | | neural_trajectory_end | Complete trajectory and run intelligence pipeline | | neural_pattern_search | Search learned patterns via keyword + semantic matching | | neural_pipeline_status | Get intelligence pipeline stats (runs, patterns, consolidation) |

Context Persistence Tools (5)

| Tool | Description | |------|-------------| | session_save | Save current session context to the archive | | session_restore | Restore archived context ranked by importance | | session_status | Get context archive status (entry count, tokens, sessions) | | session_archive | Archive multiple entries in batch with deduplication | | session_prune | Prune entries based on age, importance, or count limits |

Session Management Tools (4)

| Tool | Description | |------|-------------| | session_full_save | Save complete system state snapshot with SHA-256 checksum | | session_full_restore | Restore from snapshot with integrity verification | | session_list | List available snapshots with metadata | | session_diff | Compare two sessions, report additions/removals/changes |

Autopilot Tools (10)

| Tool | Description | |------|-------------| | autopilot_enable | Turn autopilot on, set configuration | | autopilot_disable | Turn autopilot off | | autopilot_status | Current state + iteration count + learning stats | | autopilot_config | Read/update configuration (max iterations, timeout, etc.) | | autopilot_predict | Predict optimal next action from current state | | autopilot_progress | Aggregate progress across task/file/goal sources | | autopilot_learn | Record iteration outcome for training | | autopilot_history | Browse past iterations with outcomes | | autopilot_log | Append structured log entry | | autopilot_reset | Clear state (for testing) |

Goal Planning Tools (8)

| Tool | Description | |------|-------------| | goal_create | Create a new goal with description and success criteria | | goal_plan | Run GOAP planner to decompose goal into action sequence | | goal_status | Get current goal state + progress + drift indicator | | goal_list | List all goals with status summary | | goal_complete | Mark goal as complete, trigger neural learning | | goal_research | Run multi-source research for a goal | | horizon_track | Create/update a cross-session horizon with milestones | | horizon_status | Get horizon progress + drift detection |

Skill Synthesis Tools (4)

| Tool | Description | |------|-------------| | skill_candidates | List pending skill candidates in staging area | | skill_promote | Manually promote a staged skill to .kiro/skills/learned/ | | skill_status | Get skill synthesis engine status | | skill_generate | Manually trigger skill synthesis for a specific pattern |

Hook Tools (4)

| Tool | Description | |------|-------------| | hook_register | Register a custom hook for an event | | hook_list | List registered hooks with optional filter | | hook_emit | Manually emit a hook event (for testing/triggering) | | hook_stats | Get hook execution statistics |

Worker Tools (5)

| Tool | Description | |------|-------------| | worker_run | Run a specific worker immediately | | worker_list | List all workers with their metrics | | worker_status | Get worker system status | | worker_start | Start the worker scheduler | | worker_stop | Stop the worker scheduler |

Plugin Tools (4)

| Tool | Description | |------|-------------| | plugin_list | List all installed plugins with status and tool count | | plugin_install | Install a plugin from npm package or local path | | plugin_remove | Remove an installed plugin | | plugin_status | Get detailed status of a specific plugin |

Model Routing Tools (6)

| Tool | Description | |------|-------------| | model_route | Get model recommendation based on complexity and budget | | model_record | Record model usage outcome for cost tracking and learning | | model_cost | Get cost summary for a time period (today/week/month) | | model_config | Get or update routing configuration (default model, budgets) | | model_list | List available models with pricing and capabilities | | model_status | Get routing system status and budget health |

Cost & Budget Tools (4)

| Tool | Description | |------|-------------| | cost_budget_set | Configure budget limits and enforcement mode | | cost_budget_status | Current spend vs limits + projection | | cost_alert_list | Recent budget alerts with severity | | cost_optimize | Suggestions for reducing cost (identify expensive patterns) |

Security Tools (4)

| Tool | Description | |------|-------------| | security_scan | Scan text for threats (injection, PII, validation issues) | | security_audit | Get recent security events from the audit log | | security_policy | Get or update MCP governance policy | | security_status | Get overall security system health and stats |

Workflow Tools (10)

| Tool | Description | |------|-------------| | workflow_create | Create a new workflow with steps and dependencies | | workflow_run | Execute a workflow with optional input parameters | | workflow_status | Get workflow execution status and step progress | | workflow_list | List workflows with optional status/template filter | | workflow_pause | Pause a running workflow at the next step | | workflow_resume | Resume a paused workflow from where it stopped | | workflow_cancel | Cancel a running workflow and clean up resources | | workflow_delete | Delete a workflow definition and its execution history | | workflow_step_status | Get detailed status of a specific workflow step | | workflow_template | Create or retrieve workflow templates for reuse |

Observability Tools (6)

| Tool | Description | |------|-------------| | trace_list | List distributed traces with optional filters | | trace_get | Get detailed trace information with spans | | trace_search | Search traces by operation, duration, or tags | | metrics_summary | Get overview of all system metrics | | metrics_get | Get specific metric values and time series | | observability_status | Get observability system health and configuration |

ADR Tools (5)

| Tool | Description | |------|-------------| | adr_create | Create a new ADR with auto-numbering (MADR template) | | adr_list | List all ADRs with optional status filter | | adr_get | Get specific ADR content by number | | adr_update | Update ADR status or content | | adr_search | Search ADRs by keyword across all fields |

Federation Tools (6 — stubs, transport not yet implemented)

| Tool | Description | |------|-------------| | federation_init | Initialize the local federation node | | federation_join | Join a federation peer by endpoint URL | | federation_peers | List known peers with trust levels | | federation_send | Send a signed message to a peer | | federation_status | Get federation node status | | federation_trust | Get or manage trust levels for peers |

System Tools (2)

| Tool | Description | |------|-------------| | system_status | Get current system metrics (agents, tasks, memories, uptime) | | system_health | Check persistence files and system health |

Security

Leyline includes built-in security infrastructure that protects against adversarial inputs and provides observability.

Features:

• Input Validation — detects command injection, path traversal, SQL injection, null bytes, unicode attacks
• Prompt Injection Detection — pattern-based detection for role overrides, instruction manipulation, jailbreaks
• PII Detection — identifies emails, phone numbers, SSNs, credit cards, API keys before storage
• MCP Governance Policy — rate limits, blocked patterns, namespace restrictions via .leyline/mcp-policy.json
• Security Audit Log — persistent trail of all security events in .leyline/security-audit.json

Integration: Security checks run automatically via hooks on every tool call (Critical priority). Configure behavior through the governance policy or use security_scan for on-demand scanning.

See docs/SECURITY.md for full configuration guide.

Plugin System

Leyline supports plugins that extend the system with additional MCP tools. Plugins are ESM modules that export a leylinePlugin object.

Installing Plugins

leyline plugin install <npm-package>       # From npm
leyline plugin install ./my-local-plugin   # From local path

Creating Plugins

leyline plugin create my-feature    # Scaffolds leyline-plugin-my-feature/

Plugin API

import type { LeylinePlugin } from '@focuslabs/leyline';

export const leylinePlugin: LeylinePlugin = {
  metadata: {
    name: 'leyline-plugin-example',
    version: '1.0.0',
    description: 'My custom plugin',
  },
  tools: [{
    name: 'my_custom_tool',
    description: 'Does something useful',
    inputSchema: { type: 'object', properties: { input: { type: 'string' } } },
    handler: async (args) => ({
      content: [{ type: 'text', text: JSON.stringify({ result: args.input }) }],
    }),
  }],
  async initialize(context) { /* setup */ },
  async shutdown() { /* cleanup */ },
};

Vector Search

Leyline includes hybrid search combining BM25 keywords with vector similarity (HNSW index) for better semantic retrieval.

Providers:

• TF-IDF (default) — zero dependencies, works immediately
• Transformers.js — local ONNX model, high quality, optional install
• OpenAI — API-based, highest quality, requires key

See docs/VECTOR_SEARCH.md for full configuration and tuning guide.

Intelligence Pipeline

The system automatically learns from task executions through a 4-step pipeline:

1. RETRIEVE — Pull relevant patterns via HNSW semantic + BM25 keyword search
2. JUDGE — Score candidates with quality scoring and learn/skip decisions
3. DISTILL — Extract strategies, domain classifications, and keywords
4. CONSOLIDATE — EWC-protected decay, Jaccard deduplication, short→long-term promotion

Patterns that reach high confidence (≥0.9) and usage (≥5) are automatically synthesized into Kiro skill files at .kiro/skills/learned/.

Development

npm install           # Install dependencies
npm run build         # Compile TypeScript
npm test              # Run tests (1454 tests)
npm run dev           # Watch mode compilation

Requirements

• Node.js ≥ 20.0.0
• npm

Tech Stack

| Component | Choice | |-----------|--------| | Language | TypeScript (ESM) | | CLI parsing | node:util parseArgs | | MCP transport | stdio (JSON-RPC 2.0) | | Validation | Zod | | Persistence | JSON files in .leyline/ | | Vector search | Custom HNSW (pure TypeScript) | | Embeddings | TF-IDF / Transformers.js / OpenAI | | Intelligence | 4-step pipeline (RETRIEVE→JUDGE→DISTILL→CONSOLIDATE) | | Goal planning | GOAP with A* search | | Graph ranking | PageRank (power iteration) | | Test framework | Vitest |

Project Status

• [x] Phase 1: Project scaffold, CLI, MCP server, core tools (13 tools)
• [x] Phase 2: Vector Memory + HNSW Search (3 tools)
• [x] Phase 3: Swarm Coordination + Topologies (8 tools)
• [x] Phase 4: Neural Learning + Self-Improvement (4 tools)
• [x] Phase 5: Hooks + Background Workers (9 tools)
• [x] Phase 6: Plugin System (4 tools)
• [x] Phase 7: Multi-Provider Model Routing (6 tools)
• [x] Phase 8: Security + AIDefence (4 tools)
• [x] Phase 9: Workflow Engine + DAG Execution (10 tools)
• [x] Phase 10: Observability + Distributed Tracing (6 tools)
• [x] Phase 11: Intelligence & Context Layer (14 tools)
• [x] Phase 12: Autonomy & Goals Layer (22 tools)
• [x] Phase 13: Memory Intelligence Layer (6 tools)
• [x] Phase 14: DevOps & Architecture Layer (9 tools)
• [x] Phase 15: Federation Design & Documentation (6 tools)
• [ ] Phase 16: Federation Transport Implementation
• [ ] Phase 17: Browser Automation Integration
• [ ] Phase 18: Test Generation Engine
• [ ] Phase 19: SPARC Methodology Integration
• [ ] Phase 20: Multi-Workspace Sync
• [ ] Phase 21: Production Hardening

License

MIT