@11agents/cli 0.1.3 → 0.1.5

package/README.md

@@ -27,6 +27,16 @@ export ELEVENAGENTS_SERVER="http://localhost:8082"
 
 On startup, the CLI prints its current version and target server to stderr. It also checks npm for a newer `@11agents/cli` package and prints an upgrade command when one is available.
 
+Project-scoped MCP and knowledge-base sync tokens can be stored in `~/.11agents/credentials`:
+
+```yaml
+# tokens:
+flatkey: gtm_xxxxxxxxxxxxxxxxxxxx
+voc-ai: gtm_yyyyyyyyyyyyyyyyyyyy
+```
+
+When syncing a project knowledge base, the CLI chooses tokens in this order: explicit tool/command token, matching project token from `~/.11agents/credentials`, `GTM_SWARM_TOKEN`, then the daemon control token as a compatibility fallback.
+
 ## Runtime Pool
 
 Scan local AI runtimes:
@@ -60,18 +70,20 @@ Background mode writes its pid to `~/.11agents/daemon.pid` and logs to `~/.11age
 Useful daemon options:
 
 ```bash
-11agents daemon start --heartbeat-interval 15 --scan-interval 60 --task-interval 15
+11agents daemon start --heartbeat-interval 15 --scan-interval 60 --task-interval 15 --project-refresh-interval 1800
 11agents daemon start --handler ./worker.js
 ```
 
-Before a claimed task is handed to the built-in Codex worker, the daemon prepares a local read-only project cache:
+On startup, and every 30 minutes after that, the daemon syncs project metadata and prepares local project headquarters:
 
-- Cloud database snapshot: `~/.11agents/projects/<project>/database/snapshot.json`
-- Project knowledge base: `~/.11agents/projects/<project>/knowledge_base/`
-- Skill sync state: `~/.11agents/projects/<project>/skills-state.json`
-- Task scratch directory: `~/.11agents/projects/<project>/tmp/<taskId>/`
+- Project headquarters: `~/.11agents/<project>/`
+- Project knowledge base: `~/.11agents/<project>/knowledge_base/`
+- Agent QMD memory: `~/.11agents/<project>/agents/<agent>/memory/`
+- Agent-local skills: `~/.11agents/<project>/agents/<agent>/skills/`
+- Cloud database snapshot: `~/.11agents/<project>/database/snapshot.json`
+- Task scratch directory: `~/.11agents/<project>/tmp/<taskId>/`
 
-Codex runs from `~/.11agents/projects/<project>/` by default. Treat that directory as read-only project context. Task code may write temporary files only under `./tmp/<taskId>/`; the daemon removes that task scratch directory after the task finishes. Agent environment variables from the control plane are injected into the Codex child process and are not written to disk.
+Codex runs from `~/.11agents/<project>/` by default. Treat that directory as read-only project context. Task code may write temporary files only under `./tmp/<taskId>/`; the daemon removes that task scratch directory after the task finishes. Agent environment variables from the control plane are injected into the Codex child process and are not written to disk.
 
 The built-in task runner currently supports Codex tasks. A custom handler may export:
 
@@ -85,6 +97,18 @@ export async function handleRuntimeTask(task) {
 }
 ```
 
+## MCP Project Sync Server
+
+Run the local MCP server over stdio:
+
+```bash
+11agents mcp start
+```
+
+Configure your MCP client to run that command. The server automatically reads matching project tokens from `~/.11agents/credentials`; a tool-call token can still be passed explicitly when needed. The server exposes:
+
+- `knowledge_sync` — pull/push the project knowledge base between cloud and `~/.11agents/<project>/knowledge_base/`.
+
 ## Telemetry Compatibility
 
 The package still includes the original `gtm-swarm` binary for swarm telemetry compatibility.

package/bin/11agents.js

@@ -9,6 +9,7 @@ import { registerRuntime, scanRuntime, startRuntimeDaemon } from '../src/command
 import { startBackgroundDaemon, statusBackgroundDaemon, stopBackgroundDaemon } from '../src/daemon-process.js'
 import { getControlConfig } from '../src/client.js'
 import { CLI_VERSION, printStartupInfo } from '../src/info.js'
+import { startMcpServer } from '../src/mcp.js'
 import { validateTelemetryBatch } from '../src/schema.js'
 
 function usage() {
@@ -18,10 +19,11 @@ Usage:
   11agents help
   11agents runtime scan
   11agents runtime register [--server <url>] [--token <token>] [--machine <key>]
-  11agents daemon start [--server <url>] [--token <token>] [--machine <key>] [--task-interval <seconds>] [--background]
+  11agents daemon start [--server <url>] [--token <token>] [--machine <key>] [--task-interval <seconds>] [--project-refresh-interval <seconds>] [--background]
   11agents daemon status
   11agents daemon stop
   11agents daemon start --handler ./worker.js  # optional custom worker override
+  11agents mcp start
   11agents validate <file>
   11agents push batch <file>
   11agents push artifact --workspace <slug> --agent <key> --platform x --type post --external-id <id>
@@ -36,11 +38,14 @@ Environment:
   GTM_WRITES_TOKEN     control-plane token for runtime registration
   ELEVENAGENTS_MACHINE stable machine key, defaults to hostname
   GTM_SWARM_TOKEN      project swarm token for push/node commands
+  ~/.11agents/credentials project token map for MCP knowledge sync
 
 Runtime task workspace:
-  Built-in Codex tasks run from ~/.11agents/projects/<project>/ by default.
-  That directory is read-only project context. Temporary writes belong under
-  ./tmp/<taskId>/ and are cleaned by the daemon after the task finishes.`)
+  Daemon project headquarters live under ~/.11agents/<project>/.
+  Knowledge lives under knowledge_base/. Agent QMD memory lives under
+  agents/<agent>/memory/. Agent-local skills live under agents/<agent>/skills/.
+  Built-in Codex tasks run from ~/.11agents/<project>/ by default. Temporary
+  writes belong under ./tmp/<taskId>/ and are cleaned after the task finishes.`)
 }
 
 async function main() {
@@ -105,6 +110,11 @@ async function main() {
     return
   }
 
+  if (command === 'mcp' && (!subcommand || subcommand === 'start')) {
+    await startMcpServer()
+    return
+  }
+
   if (command === 'validate') {
     const file = subcommand
     if (!file) throw new Error('validate requires a file')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@11agents/cli",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "11agents local runtime and telemetry CLI",
   "type": "module",
   "bin": {

package/src/commands/data-collection.js

@@ -0,0 +1,95 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { requestJson } from '../client.js'
+
+function slugify(value) {
+  return String(value || '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+}
+
+function projectDir(project, { homeDir = os.homedir() } = {}) {
+  return path.join(homeDir, '.11agents', slugify(project))
+}
+
+function formatsDir(project, options) {
+  return path.join(projectDir(project, options), 'data-formats')
+}
+
+function schemaPath(project, dataset, options) {
+  return path.join(formatsDir(project, options), `${slugify(dataset)}.json`)
+}
+
+function validateValue(value, schema, label) {
+  const type = schema?.type
+  if (!type) return
+  if (type === 'number' && typeof value !== 'number') throw new Error(`${label} must be number`)
+  if (type === 'integer' && (!Number.isInteger(value))) throw new Error(`${label} must be integer`)
+  if (type === 'string' && typeof value !== 'string') throw new Error(`${label} must be string`)
+  if (type === 'boolean' && typeof value !== 'boolean') throw new Error(`${label} must be boolean`)
+  if (type === 'array' && !Array.isArray(value)) throw new Error(`${label} must be array`)
+  if (type === 'object' && (typeof value !== 'object' || value === null || Array.isArray(value))) throw new Error(`${label} must be object`)
+}
+
+export function validateRowsAgainstSchema(rows, schema) {
+  if (!Array.isArray(rows)) throw new Error('rows must be an array')
+  const required = Array.isArray(schema?.required) ? schema.required : []
+  const properties = schema?.properties && typeof schema.properties === 'object' ? schema.properties : {}
+  rows.forEach((row, index) => {
+    if (!row || typeof row !== 'object' || Array.isArray(row)) throw new Error(`rows[${index}] must be object`)
+    for (const key of required) {
+      if (row[key] === undefined || row[key] === null || row[key] === '') throw new Error(`rows[${index}].${key} is required`)
+    }
+    for (const [key, propertySchema] of Object.entries(properties)) {
+      if (row[key] !== undefined && row[key] !== null) validateValue(row[key], propertySchema, `rows[${index}].${key}`)
+    }
+  })
+}
+
+export async function defineDataFormat({ project, dataset, schema, token = '', server = '' } = {}, deps = {}) {
+  if (!project) throw new Error('project is required')
+  if (!dataset) throw new Error('dataset is required')
+  if (!schema || typeof schema !== 'object' || schema.type !== 'object') throw new Error('schema must be a JSON object schema')
+  const homeDir = deps.homeDir || os.homedir()
+  const request = deps.requestJson || requestJson
+  const result = await request(`/api/projects/${slugify(project)}/data/formats`, {
+    method: 'POST',
+    body: { dataset: slugify(dataset), schema },
+    config: { token, server: server || 'https://app.11agents.ai' },
+  })
+  await mkdir(formatsDir(project, { homeDir }), { recursive: true })
+  await writeFile(schemaPath(project, dataset, { homeDir }), JSON.stringify({
+    dataset: slugify(dataset),
+    schema,
+    schema_revision: Number(result?.schema_revision || 1),
+    defined_at: new Date().toISOString(),
+  }, null, 2))
+  return result
+}
+
+async function readLockedFormat(project, dataset, { homeDir = os.homedir() } = {}) {
+  return JSON.parse(await readFile(schemaPath(project, dataset, { homeDir }), 'utf8'))
+}
+
+export async function pushDataRows({ project, dataset, date, rows, token = '', server = '' } = {}, deps = {}) {
+  if (!project) throw new Error('project is required')
+  if (!dataset) throw new Error('dataset is required')
+  if (!date) throw new Error('date is required')
+  const homeDir = deps.homeDir || os.homedir()
+  const locked = await readLockedFormat(project, dataset, { homeDir })
+  validateRowsAgainstSchema(rows, locked.schema)
+  const request = deps.requestJson || requestJson
+  return request(`/api/projects/${slugify(project)}/data/push`, {
+    method: 'POST',
+    body: {
+      dataset: slugify(dataset),
+      date,
+      schema_revision: locked.schema_revision,
+      rows,
+    },
+    config: { token, server: server || 'https://app.11agents.ai' },
+  })
+}

package/src/commands/database.js

@@ -0,0 +1,60 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { requestJson } from '../client.js'
+
+function slugify(value) {
+  return String(value || 'project')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '') || 'project'
+}
+
+export function buildDatabaseDir(project, { homeDir = os.homedir() } = {}) {
+  return path.join(homeDir, '.11agents', slugify(project), 'database')
+}
+
+async function readState(project, { homeDir = os.homedir() } = {}) {
+  try {
+    return JSON.parse(await readFile(path.join(buildDatabaseDir(project, { homeDir }), 'sync-state.json'), 'utf8'))
+  } catch {
+    return {}
+  }
+}
+
+export async function syncDatabase({ project, mode = 'pull', token = '', server = '' } = {}, deps = {}) {
+  if (!project) throw new Error('database sync requires project')
+  const homeDir = deps.homeDir || os.homedir()
+  const request = deps.requestJson || requestJson
+  const dir = buildDatabaseDir(project, { homeDir })
+  const state = await readState(project, { homeDir })
+  const body = {
+    mode,
+    local_revision: Number(state.cloud_revision || 0),
+  }
+  if (mode === 'push') {
+    body.snapshot = JSON.parse(await readFile(path.join(dir, 'snapshot.json'), 'utf8'))
+  }
+  const result = await request(`/api/projects/${slugify(project)}/database/sync`, {
+    method: 'POST',
+    body,
+    config: { token, server: server || 'https://app.11agents.ai' },
+  })
+  await mkdir(dir, { recursive: true })
+  if (result?.snapshot !== undefined) {
+    await writeFile(path.join(dir, 'snapshot.json'), JSON.stringify(result.snapshot, null, 2))
+  }
+  await writeFile(path.join(dir, 'sync-state.json'), JSON.stringify({
+    cloud_revision: Number(result?.cloud_revision || 0),
+    synced_at: result?.synced_at || new Date().toISOString(),
+  }, null, 2))
+  return {
+    ok: true,
+    project: slugify(project),
+    mode,
+    path: dir,
+    cloud_revision: Number(result?.cloud_revision || 0),
+    synced_at: result?.synced_at || '',
+  }
+}

package/src/commands/knowledge.js

@@ -1,4 +1,4 @@
-import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises'
 import os from 'node:os'
 import path from 'node:path'
 import { flag } from '../args.js'
@@ -18,6 +18,8 @@ function safeLocalPath(value, id) {
   return `nodes/${slugify(id)}.md`
 }
 
+const MARKDOWN_NODE_KINDS = new Set(['document', 'fact', 'decision', 'insight', 'resource', 'task-context'])
+
 function normalizeSnapshot(snapshot = {}) {
   return {
     cloud_revision: Number(snapshot.cloud_revision || snapshot.knowledge_base?.cloud_revision || 0),
@@ -68,8 +70,50 @@ function bodyFromMarkdownNode(markdown, fallback = '') {
   return body || fallback
 }
 
+function isKnowledgeTextFile(name) {
+  return name.endsWith('.md') || name === 'llms.txt' || name === 'llms-full.txt'
+}
+
+async function listKnowledgeTextFiles(baseDir, currentDir = baseDir) {
+  const entries = await readdir(currentDir, { withFileTypes: true }).catch(() => [])
+  const files = []
+  for (const entry of entries) {
+    if (entry.name.startsWith('.')) continue
+    const fullPath = path.join(currentDir, entry.name)
+    if (entry.isDirectory()) {
+      files.push(...await listKnowledgeTextFiles(baseDir, fullPath))
+      continue
+    }
+    if (!entry.isFile() || !isKnowledgeTextFile(entry.name)) continue
+    files.push(path.relative(baseDir, fullPath).split(path.sep).join('/'))
+  }
+  return files.sort((a, b) => a.localeCompare(b))
+}
+
+function titleFromLocalPath(localPath) {
+  const basename = path.basename(localPath).replace(/\.(md|txt)$/i, '')
+  if (basename.toLowerCase() === 'readme') return 'README'
+  if (basename.toLowerCase() === 'claude') return 'Agent Instructions'
+  if (basename.toLowerCase() === 'index') return 'Knowledge Map'
+  return basename
+    .split(/[-_]+/)
+    .filter(Boolean)
+    .map(part => `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`)
+    .join(' ') || localPath
+}
+
+function kindFromLocalPath(localPath) {
+  const folder = localPath.split('/').filter(Boolean)[0]
+  if (MARKDOWN_NODE_KINDS.has(folder)) return folder
+  if (folder === 'resources') return 'resource'
+  if (folder === 'decisions') return 'decision'
+  if (folder === 'insights') return 'insight'
+  if (folder === 'tasks') return 'task-context'
+  return 'document'
+}
+
 export function buildKnowledgeBaseDir(project, { homeDir = os.homedir() } = {}) {
-  return path.join(homeDir, '.11agents', 'projects', slugify(project), 'knowledge_base')
+  return path.join(homeDir, '.11agents', slugify(project), 'knowledge_base')
 }
 
 export async function writeKnowledgeSnapshot(project, snapshot, { homeDir = os.homedir() } = {}) {
@@ -101,12 +145,24 @@ export async function readKnowledgeSnapshot(project, { homeDir = os.homedir() }
   const baseDir = buildKnowledgeBaseDir(project, { homeDir })
   const raw = await readFile(path.join(baseDir, 'index.json'), 'utf-8').catch(() => '{}')
   const snapshot = normalizeSnapshot(JSON.parse(raw))
-  const nodes = await Promise.all(snapshot.nodes.map(async node => {
+  const nodesByPath = new Map(snapshot.nodes.map(node => [node.local_path, node]))
+  for (const localPath of await listKnowledgeTextFiles(baseDir)) {
+    if (nodesByPath.has(localPath)) continue
+    nodesByPath.set(localPath, {
+      id: slugify(localPath.replace(/\.(md|txt)$/i, '')),
+      kind: kindFromLocalPath(localPath),
+      title: titleFromLocalPath(localPath),
+      body: '',
+      local_path: localPath,
+      metadata: { source: 'local-markdown' },
+    })
+  }
+  const nodes = await Promise.all([...nodesByPath.values()].map(async node => {
     const markdown = await readFile(path.join(baseDir, node.local_path), 'utf-8').catch(() => null)
     if (markdown === null) return node
     return { ...node, body: bodyFromMarkdownNode(markdown, node.body) }
   }))
-  return { ...snapshot, nodes }
+  return { ...snapshot, nodes: nodes.sort((a, b) => a.id.localeCompare(b.id)) }
 }
 
 export async function syncKnowledge(flags = {}, deps = {}) {

package/src/commands/runtime.js

@@ -1,7 +1,7 @@
 import { spawn } from 'node:child_process'
 import { createHash } from 'node:crypto'
 import { readFileSync } from 'node:fs'
-import { mkdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { appendFile, mkdir, readFile, rm, writeFile } from 'node:fs/promises'
 import os from 'node:os'
 import { dirname, resolve } from 'node:path'
 import path from 'node:path'
@@ -9,8 +9,10 @@ import { pathToFileURL } from 'node:url'
 import { fileURLToPath } from 'node:url'
 import { flag } from '../args.js'
 import { getControlConfig, requestJson } from '../client.js'
+import { resolveProjectToken } from '../credentials.js'
 import { syncKnowledge } from './knowledge.js'
 import { buildRuntimeScan } from '../runtime-scan.js'
+import { handleMcpRequest } from '../mcp.js'
 
 const CLI_VERSION = JSON.parse(readFileSync(resolve(dirname(fileURLToPath(import.meta.url)), '../../package.json'), 'utf-8')).version
 
@@ -66,6 +68,7 @@ function runtimeDeps(overrides = {}) {
     requestJson: overrides.requestJson || requestJson,
     sleep: overrides.sleep || sleep,
     syncKnowledge: overrides.syncKnowledge || syncKnowledge,
+    mcpKnowledgeSync: overrides.mcpKnowledgeSync || mcpKnowledgeSync,
   }
 }
 
@@ -147,6 +150,37 @@ export async function heartbeatRuntime(flags = {}, deps = {}) {
   return result
 }
 
+export async function syncRuntimeProjectMetadata(flags = {}, deps = {}) {
+  const { log, requestJson: request, homeDir } = runtimeDeps(deps)
+  const config = configFromFlags(flags)
+  if (!config.token) throw new Error('GTM_WRITES_TOKEN or --token is required')
+
+  const result = await request('/api/runtime/projects', {
+    method: 'GET',
+    config,
+  })
+  const materialized = await materializeRuntimeProjectDirectories(result?.projects || [], { homeDir })
+  log(JSON.stringify({
+    ok: true,
+    synced: 'runtime projects',
+    base_dir: materialized.base_dir,
+    projects: materialized.projects,
+  }, null, 2))
+  return { ...result, ...materialized }
+}
+
+async function syncRuntimeProjectMetadataBestEffort(flags, deps) {
+  try {
+    return await syncRuntimeProjectMetadata(flags, deps)
+  } catch (error) {
+    deps.log(JSON.stringify({
+      warning: 'runtime project metadata sync failed',
+      error: errorMessage(error),
+    }, null, 2))
+    return null
+  }
+}
+
 function normalizeTaskCompletion(task, completion) {
   const result = completion && typeof completion === 'object' ? completion : {}
   return {
@@ -172,6 +206,27 @@ function compactJson(value) {
   return JSON.stringify(value ?? null, null, 2)
 }
 
+async function mcpKnowledgeSync(flags = {}, deps = {}) {
+  const token = await resolveProjectToken(flags.project, {
+    homeDir: deps.homeDir,
+    token: flags.projectToken,
+    fallbackToken: flags.token,
+  })
+  const result = await handleMcpRequest({
+    method: 'tools/call',
+    params: {
+      name: 'knowledge_sync',
+      arguments: {
+        project: flags.project,
+        mode: flags.mode,
+        server: flags.server,
+        token,
+      },
+    },
+  }, deps)
+  return JSON.parse(result.content?.[0]?.text || '{}')
+}
+
 const nonAlphaNum = /[^a-z0-9]+/g
 
 function slugify(value, fallback = 'project') {
@@ -186,12 +241,99 @@ function sanitizeTaskId(value) {
   return slugify(value, 'task')
 }
 
+export function buildRuntimeProjectDir(project, { homeDir = os.homedir() } = {}) {
+  return path.join(homeDir, '.11agents', slugify(project))
+}
+
+export function buildRuntimeKnowledgeDir(project, { homeDir = os.homedir() } = {}) {
+  return path.join(buildRuntimeProjectDir(project, { homeDir }), 'knowledge_base')
+}
+
+export function buildRuntimeAgentMemoryDir(project, agent, { homeDir = os.homedir() } = {}) {
+  return path.join(buildRuntimeProjectDir(project, { homeDir }), 'agents', slugify(agent, 'agent'), 'memory')
+}
+
+export function buildRuntimeAgentSkillsDir(project, agent, { homeDir = os.homedir() } = {}) {
+  return path.join(buildRuntimeProjectDir(project, { homeDir }), 'agents', slugify(agent, 'agent'), 'skills')
+}
+
 function projectSlugForTask(task, flags = {}) {
   return slugify(task.workspace?.slug || task.workspace_slug || flag(flags, 'project') || flag(flags, 'workspace') || 'project')
 }
 
 function projectDirForTask(task, flags = {}, deps) {
-  return path.join(deps.homeDir, '.11agents', 'projects', projectSlugForTask(task, flags))
+  return buildRuntimeProjectDir(projectSlugForTask(task, flags), { homeDir: deps.homeDir })
+}
+
+async function projectSyncToken(project, flags = {}, deps = {}) {
+  return resolveProjectToken(project, {
+    homeDir: deps.homeDir,
+    fallbackToken: flags.token,
+  })
+}
+
+async function writeFileIfMissing(filePath, content) {
+  try {
+    await writeFile(filePath, content, { flag: 'wx' })
+  } catch (error) {
+    if (error?.code !== 'EEXIST') throw error
+  }
+}
+
+function defaultMemoryQmd(project, agent) {
+  return [
+    `# ${agent.name || agent.id || 'Agent'} Memory`,
+    '',
+    `project: ${project.slug || project.name || 'project'}`,
+    `agent: ${agent.name || agent.id || 'agent'}`,
+    '',
+  ].join('\n')
+}
+
+function safeQmdName(value, fallback) {
+  const name = slugify(String(value || '').replace(/\.qmd$/i, ''), fallback)
+  return `${name}.qmd`
+}
+
+export async function materializeRuntimeProjectDirectories(projects = [], { homeDir = os.homedir() } = {}) {
+  const baseDir = path.join(homeDir, '.11agents')
+  await mkdir(baseDir, { recursive: true })
+  const written = []
+  for (const project of Array.isArray(projects) ? projects : []) {
+    const projectSlug = slugify(project?.slug || project?.name, 'project')
+    const projectDir = buildRuntimeProjectDir(projectSlug, { homeDir })
+    await mkdir(buildRuntimeKnowledgeDir(projectSlug, { homeDir }), { recursive: true })
+    written.push(projectDir)
+    for (const agent of Array.isArray(project?.agents) ? project.agents : []) {
+      const agentName = agent?.name || agent?.id || 'agent'
+      const memoryDir = buildRuntimeAgentMemoryDir(projectSlug, agentName, { homeDir })
+      const skillsDir = buildRuntimeAgentSkillsDir(projectSlug, agentName, { homeDir })
+      await mkdir(memoryDir, { recursive: true })
+      await mkdir(skillsDir, { recursive: true })
+      await writeFileIfMissing(path.join(memoryDir, 'index.qmd'), defaultMemoryQmd({ ...project, slug: projectSlug }, agent))
+      for (const memory of Array.isArray(agent?.memory) ? agent.memory : []) {
+        await writeFileIfMissing(path.join(memoryDir, safeQmdName(memory, 'memory')), '')
+      }
+      for (const skill of Array.isArray(agent?.skills) ? agent.skills : []) {
+        await mkdir(path.join(skillsDir, slugify(skill?.name || skill, 'skill')), { recursive: true })
+      }
+    }
+  }
+  return { base_dir: baseDir, projects: written.length }
+}
+
+function knowledgeDeepOrganizeSpec(task) {
+  if (task.queue_event?.trigger_type !== 'knowledge_deep_organize') return null
+  const raw = String(task.queue_event?.trigger_summary || '')
+  try {
+    const parsed = JSON.parse(raw)
+    return {
+      source_url: String(parsed.source_url || parsed.url || ''),
+      source_type: String(parsed.source_type || '').toLowerCase(),
+    }
+  } catch {
+    return { source_url: raw, source_type: raw.includes('github.com') ? 'github' : 'url' }
+  }
 }
 
 async function readJsonFile(filePath, fallback = {}) {
@@ -220,13 +362,8 @@ function decodeFileContent(file) {
   return Buffer.from(String(file?.content || ''), 'utf8')
 }
 
-function skillDirForProvider({ workdir, provider, codexHome }) {
-  if (provider === 'codex') return path.join(codexHome || path.join(os.homedir(), '.codex'), 'skills')
-  if (provider === 'claude') return path.join(workdir, '.claude', 'skills')
-  if (provider === 'copilot') return path.join(workdir, '.github', 'skills')
-  if (provider === 'opencode') return path.join(workdir, '.opencode', 'skills')
-  if (provider === 'cursor') return path.join(workdir, '.cursor', 'skills')
-  return path.join(workdir, '.agent_context', 'skills')
+function agentNameForTask(task) {
+  return task.agent?.name || task.agent?.id || task.agent_id || task.assignee_id || 'agent'
 }
 
 function normalizeSkillBundle(skill = {}) {
@@ -248,17 +385,12 @@ async function materializeSkillsIfChanged({ task, workdir, flags, deps }) {
   const skills = Array.isArray(task.agent?.skills) ? task.agent.skills.map(normalizeSkillBundle) : []
   if (!skills.length) return { changed: false, count: 0 }
 
-  const statePath = path.join(workdir, 'skills-state.json')
+  const skillsDir = path.join(workdir, 'agents', slugify(agentNameForTask(task), 'agent'), 'skills')
+  const statePath = path.join(skillsDir, 'skills-state.json')
   const nextHash = stableHash(skills)
   const current = await readJsonFile(statePath, {})
   if (current.hash === nextHash) return { changed: false, count: skills.length }
 
-  const provider = task.runtime?.provider || ''
-  const skillsDir = skillDirForProvider({
-    workdir,
-    provider,
-    codexHome: flag(flags, 'codex-home', process.env.CODEX_HOME || path.join(deps.homeDir, '.codex')),
-  })
   await mkdir(skillsDir, { recursive: true })
   for (const skill of skills) {
     const skillDir = path.join(skillsDir, slugify(skill.name, 'skill'))
@@ -280,6 +412,23 @@ async function materializeSkillsIfChanged({ task, workdir, flags, deps }) {
   return { changed: true, count: skills.length, skills_dir: skillsDir }
 }
 
+async function appendTaskMemoryDelta({ task, completion, workdir }) {
+  const memoryDelta = String(completion?.memory_delta || completion?.memoryDelta || '').trim()
+  if (!memoryDelta) return { written: false }
+  const memoryDir = path.join(workdir, 'agents', slugify(agentNameForTask(task), 'agent'), 'memory')
+  await mkdir(memoryDir, { recursive: true })
+  const indexPath = path.join(memoryDir, 'index.qmd')
+  await writeFileIfMissing(indexPath, defaultMemoryQmd({ slug: projectSlugForTask(task), name: task.workspace?.name }, task.agent || {}))
+  await appendFile(indexPath, [
+    '',
+    `## ${new Date().toISOString()} ${task.id || ''}`.trim(),
+    '',
+    memoryDelta,
+    '',
+  ].join('\n'))
+  return { written: true, path: indexPath }
+}
+
 function databaseSyncSpec(task) {
   const spec = task.database || task.cloud_database || task.workspace?.database || null
   if (!spec || typeof spec !== 'object') return null
@@ -364,6 +513,7 @@ async function prepareRuntimeTask(task, flags, deps, config) {
 }
 
 function buildCodexPrompt(task) {
+  const deepOrganize = knowledgeDeepOrganizeSpec(task)
   return [
     'You are executing an 11agents task as the assigned agent.',
     '',
@@ -401,6 +551,33 @@ function buildCodexPrompt(task) {
     '',
     'Thread comments:',
     compactJson(task.comments || []),
+    deepOrganize ? [
+      '',
+      'Knowledge deep organization task:',
+      compactJson({
+        trigger_type: 'knowledge_deep_organize',
+        source_url: deepOrganize.source_url,
+        source_type: deepOrganize.source_type || (deepOrganize.source_url.includes('github.com') ? 'github' : 'url'),
+        output_dir: task.execution_context?.workdir ? `${task.execution_context.workdir}/knowledge_base` : './knowledge_base',
+        callback: 'After organizing files, call the 11agents MCP knowledge_sync tool with mode=push so cloud receives the finished wiki.',
+      }),
+      '',
+      'Build the knowledge base using the standard llms.txt / LLM Wiki pattern popularized for LLM-readable documentation:',
+      '- Create or update ./knowledge_base/llms.txt with one H1 project title, a blockquote summary, concise context, and H2 sections containing Markdown links to the most important files.',
+      '- Create or update ./knowledge_base/llms-full.txt as a fuller single-file context pack when useful.',
+      '- Create or update ./knowledge_base/README.md, ./knowledge_base/index.md, and ./knowledge_base/CLAUDE.md as the human entry point, node map, and agent operating guide.',
+      '- Treat the finished result as an agent skill graph like a strong hand-built knowledge base: every durable file should tell the next agent exactly when to read it and how to act on it.',
+      '- Do not stop at project-profile.md / knowledge-map.md placeholders. Create concrete markdown files with actionable content.',
+      '- For product, website, or business sources, use semantic folders such as information/, voice/, audience/, marketing/, product-design/, resources/, and decisions/. Create files like information/what-we-do/product-overview.md, voice/brand-voice.md, audience/README.md, and marketing/README.md when the source supports them.',
+      '- For GitHub sources, use semantic folders such as codebase/, architecture/, api/, operations/, examples/, resources/, and agent-playbook/. Create files like codebase/README.md, architecture/overview.md, operations/setup.md, api/README.md, and examples/README.md when the repo supports them.',
+      '- README.md should include a "Where to Start" table and a directory overview.',
+      '- index.md should include Identity, Node Map, and Execution Instructions sections with wiki-style references to important files.',
+      '- CLAUDE.md should include the exact read order and output/update rules for runtime agents.',
+      '- If source_type is github, inspect README, docs, package manifests, examples, and source tree. Prefer concise durable explanations over raw dumps.',
+      '- If source_type is url, read the page and prefer /llms.txt or /llms-full.txt from that origin when available.',
+      '- Keep file paths stable and descriptive. Do not write temporary research into the durable wiki.',
+      '- When done, use MCP to push the local knowledge_base back to cloud.',
+    ].join('\n') : '',
     '',
     'Work in this repository and make the needed changes. When finished, respond with a concise summary for the task thread.',
   ].join('\n')
@@ -499,14 +676,16 @@ async function claimAndRunRuntimeTasks(registration, flags, deps, handlerModule,
 
     deps.log(JSON.stringify({ claimed: runtimeTask.id, runtime_id: runtime.id }, null, 2))
     if (runtimeTask.workspace?.slug) {
+      const token = await projectSyncToken(runtimeTask.workspace.slug, flags, deps)
+      const syncConfig = { ...config, token }
       await runWithDaemonRetry('sync knowledge base', () => (
         deps.syncKnowledge({
           project: runtimeTask.workspace.slug,
           mode: 'pull',
           server: flags.server,
-          token: flags.token,
+          token,
         }, {
-          requestJson: (apiPath, options = {}) => deps.requestJson(apiPath, { ...options, config }),
+          requestJson: (apiPath, options = {}) => deps.requestJson(apiPath, { ...options, config: syncConfig }),
           log: () => {},
         })
       ), deps, retryState)
@@ -524,16 +703,20 @@ async function claimAndRunRuntimeTasks(registration, flags, deps, handlerModule,
     } finally {
       await rm(executionContext.tmp_dir, { recursive: true, force: true })
     }
+    await appendTaskMemoryDelta({ task: runtimeTask, completion, workdir: executionContext.workdir })
 
     if (runtimeTask.workspace?.slug) {
+      const syncBack = knowledgeDeepOrganizeSpec(runtimeTask) ? deps.mcpKnowledgeSync : deps.syncKnowledge
+      const token = await projectSyncToken(runtimeTask.workspace.slug, flags, deps)
+      const syncConfig = { ...config, token }
       await runWithDaemonRetry('sync knowledge base back to cloud', () => (
-        deps.syncKnowledge({
+        syncBack({
           project: runtimeTask.workspace.slug,
           mode: 'push',
           server: flags.server,
-          token: flags.token,
+          token,
         }, {
-          requestJson: (apiPath, options = {}) => deps.requestJson(apiPath, { ...options, config }),
+          requestJson: (apiPath, options = {}) => deps.requestJson(apiPath, { ...options, config: syncConfig }),
           log: () => {},
         })
       ), deps, retryState)
@@ -559,6 +742,7 @@ export async function startRuntimeDaemon(flags = {}, deps = {}) {
   const heartbeatIntervalMs = Number(flag(flags, 'heartbeat-interval', '15')) * 1000
   const scanIntervalMs = Number(flag(flags, 'scan-interval', '60')) * 1000
   const taskIntervalMs = Number(flag(flags, 'task-interval', flag(flags, 'heartbeat-interval', '15'))) * 1000
+  const projectRefreshIntervalMs = Number(flag(flags, 'project-refresh-interval', '1800')) * 1000
   const once = Boolean(flags.once)
   const handlerPath = flag(flags, 'handler')
 
@@ -571,18 +755,23 @@ export async function startRuntimeDaemon(flags = {}, deps = {}) {
   if (!Number.isFinite(taskIntervalMs) || taskIntervalMs <= 0) {
     throw new Error('--task-interval must be a positive number of seconds')
   }
+  if (!Number.isFinite(projectRefreshIntervalMs) || projectRefreshIntervalMs <= 0) {
+    throw new Error('--project-refresh-interval must be a positive number of seconds')
+  }
 
   const handlerModule = await loadTaskHandler(handlerPath, resolvedDeps) || defaultTaskHandler(flags, resolvedDeps)
   const retryState = createRetryState()
   let registration = await runWithDaemonRetry('register runtime', () => registerRuntime(flags, resolvedDeps), resolvedDeps, retryState)
+  await syncRuntimeProjectMetadataBestEffort(flags, resolvedDeps)
   await claimAndRunRuntimeTasks(registration, flags, resolvedDeps, handlerModule, retryState)
   if (once) return
 
   let lastScan = Date.now()
   let lastHeartbeat = Date.now()
   let lastTaskPoll = Date.now()
+  let lastProjectRefresh = Date.now()
   while (true) {
-    await resolvedDeps.sleep(Math.min(heartbeatIntervalMs, taskIntervalMs))
+    await resolvedDeps.sleep(Math.min(heartbeatIntervalMs, taskIntervalMs, projectRefreshIntervalMs))
     const now = Date.now()
     if (now - lastScan >= scanIntervalMs) {
       registration = await runWithDaemonRetry('register runtime', () => registerRuntime(flags, resolvedDeps), resolvedDeps, retryState)
@@ -596,5 +785,9 @@ export async function startRuntimeDaemon(flags = {}, deps = {}) {
       await claimAndRunRuntimeTasks(registration, flags, resolvedDeps, handlerModule, retryState)
       lastTaskPoll = now
     }
+    if (now - lastProjectRefresh >= projectRefreshIntervalMs) {
+      await syncRuntimeProjectMetadataBestEffort(flags, resolvedDeps)
+      lastProjectRefresh = now
+    }
   }
 }

package/src/credentials.js

@@ -0,0 +1,70 @@
+import { readFile } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+
+function slugify(value) {
+  return String(value || 'project')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '') || 'project'
+}
+
+function cleanHeader(value) {
+  return String(value || '').trim().replace(/^#\s*/, '').trim()
+}
+
+export function parseCredentials(content = '') {
+  const tokens = {}
+  let inTokens = false
+
+  for (const rawLine of String(content).split(/\r?\n/)) {
+    const line = rawLine.trim()
+    if (!line) continue
+
+    const header = cleanHeader(line)
+    if (/^tokens\s*:\s*$/.test(header)) {
+      inTokens = true
+      continue
+    }
+    if (line.startsWith('#')) continue
+
+    const match = line.match(/^([^:#]+):\s*(.+)$/)
+    if (!match) {
+      inTokens = false
+      continue
+    }
+    if (!inTokens && Object.keys(tokens).length === 0) inTokens = true
+    if (!inTokens) continue
+
+    const project = slugify(match[1])
+    const token = match[2].trim()
+    if (project && token) tokens[project] = token
+  }
+
+  return { tokens }
+}
+
+export async function readCredentials({ homeDir = os.homedir() } = {}) {
+  try {
+    return parseCredentials(await readFile(path.join(homeDir, '.11agents', 'credentials'), 'utf8'))
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { tokens: {} }
+    throw error
+  }
+}
+
+export async function resolveProjectToken(project, {
+  homeDir = os.homedir(),
+  token = '',
+  fallbackToken = '',
+  env = process.env,
+} = {}) {
+  if (token) return token
+
+  const credentials = await readCredentials({ homeDir })
+  const projectToken = credentials.tokens[slugify(project)]
+  if (projectToken) return projectToken
+
+  return env.GTM_SWARM_TOKEN || fallbackToken || ''
+}

package/src/mcp.js

@@ -0,0 +1,105 @@
+import { syncKnowledge } from './commands/knowledge.js'
+import { requestJson } from './client.js'
+import { resolveProjectToken } from './credentials.js'
+
+const TOOLS = [
+  {
+    name: 'knowledge_sync',
+    description: 'Pull cloud project knowledge to local disk or push local project knowledge back to cloud with a project token.',
+    inputSchema: {
+      type: 'object',
+      required: ['project', 'mode'],
+      properties: {
+        project: { type: 'string' },
+        mode: { type: 'string', enum: ['pull', 'push'] },
+        token: { type: 'string' },
+        server: { type: 'string' },
+      },
+    },
+  },
+]
+
+function textResult(value) {
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify(value, null, 2),
+    }],
+  }
+}
+
+function toolArgs(request) {
+  return request?.params?.arguments || {}
+}
+
+export async function handleMcpRequest(request, deps = {}) {
+  if (request.method === 'initialize') {
+    return {
+      protocolVersion: '2024-11-05',
+      capabilities: { tools: {} },
+      serverInfo: { name: '11agents-project-sync', version: '0.1.0' },
+    }
+  }
+  if (request.method === 'tools/list') return { tools: TOOLS }
+  if (request.method !== 'tools/call') throw new Error(`unsupported MCP method: ${request.method}`)
+
+  const name = request?.params?.name
+  const args = toolArgs(request)
+  if (name === 'knowledge_sync') {
+    const token = await resolveProjectToken(args.project, {
+      homeDir: deps.homeDir,
+      token: args.token,
+    })
+    const result = await syncKnowledge({
+      project: args.project,
+      mode: args.mode,
+      server: args.server,
+      token,
+    }, {
+      ...deps,
+      requestJson: (apiPath, options = {}) => (deps.requestJson || requestJson)(apiPath, {
+        ...options,
+        config: { token, server: args.server || 'https://app.11agents.ai' },
+      }),
+    })
+    return textResult(result)
+  }
+  throw new Error(`unknown MCP tool: ${name}`)
+}
+
+function jsonRpcError(id, error) {
+  return {
+    jsonrpc: '2.0',
+    id,
+    error: {
+      code: -32000,
+      message: error instanceof Error ? error.message : String(error),
+    },
+  }
+}
+
+export async function startMcpServer({ input = process.stdin, output = process.stdout, deps = {} } = {}) {
+  input.setEncoding('utf8')
+  let buffer = ''
+  input.on('data', chunk => {
+    buffer += chunk
+    let index = buffer.indexOf('\n')
+    while (index >= 0) {
+      const line = buffer.slice(0, index).trim()
+      buffer = buffer.slice(index + 1)
+      index = buffer.indexOf('\n')
+      if (!line) continue
+      ;(async () => {
+        let request
+        try {
+          request = JSON.parse(line)
+          if (!request.id && request.method === 'notifications/initialized') return
+          const result = await handleMcpRequest(request, deps)
+          output.write(`${JSON.stringify({ jsonrpc: '2.0', id: request.id, result })}\n`)
+        } catch (error) {
+          output.write(`${JSON.stringify(jsonRpcError(request?.id || null, error))}\n`)
+        }
+      })()
+    }
+  })
+}