@aistastudio/myc 0.1.0

package/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 aistastudio
+
+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,156 @@
+# myc
+
+A local, fast task-and-memory layer for coding agents: a task queue, an oplog of
+facts and decisions, and hybrid (lexical + vector) search over the project's
+memory — with no network calls and no mandatory LLM key.
+
+Agents forget. `myc` is the part that doesn't: decisions survive context
+compaction, work survives process death, and both survive being moved between
+machines through plain git.
+
+Design docs live in `docs/design/` (start with `00-brief.md`); the measurements
+quoted below are reproducible from `bench/` and `scripts/`.
+
+## Requires Bun — this is not fine print
+
+The runtime is bound to `bun:sqlite` (SQLite and `sqlite-vec` ship inside Bun,
+with no native bindings on the Node side). **It will not start on plain Node.js
+or Deno.** Bun ≥ 1.3.0 is required and pinned in `package.json` → `engines.bun`.
+
+Install Bun: https://bun.sh
+
+## Install
+
+Once published, installation is one command — the package is built and verified
+from a tarball today, but nothing has been pushed to the registry yet:
+
+```bash
+bun add @aistastudio/myc     # 3.16 MB, 9 files, no models pulled at install
+bunx myc --version
+```
+
+The embedding model is **not** downloaded during install. Semantic search is
+opt-in and explicit: `myc models fetch` (129 MB, ~7 s). Until then search is
+lexical and says so.
+
+Until it is published, build from source:
+
+```bash
+git clone <repo> && cd myc
+bun install
+bun run build          # produces a single binary: dist/myc
+./dist/myc --version
+```
+
+Put the binary somewhere `myc wire` can find it — `MYC_BIN`, `node_modules/.bin`,
+`~/.myc/bin/myc`, or `PATH`. If it can't, `wire` says so out loud instead of
+writing a config that silently won't start.
+
+## Quick start
+
+```bash
+./dist/myc init                     # .myc/ + SQLite + migrations in this repo
+./dist/myc wire                     # hooks for Claude Code / Codex / opencode
+./dist/myc ready                    # what can be picked up right now
+./dist/myc remember "why X, not Y"  # record a fact or decision
+./dist/myc recall "how retrieval works"
+./dist/myc prime                    # session context packet (agents call it)
+```
+
+Full command list: `./dist/myc --help`.
+
+## What makes it different
+
+**Speed is a constraint, not an optimisation.** Every hot path has a budget
+enforced in CI; a p95 regression over 15% fails the build. Measured on 100 000
+nodes (`bun run scripts/bench-latency.ts`):
+
+| operation | p99 | budget |
+|---|---|---|
+| `prime` (session context) | 0.70 ms | 30 ms |
+| read | 0.011 ms | 3 ms |
+| search | 9.1 ms | 25 ms |
+| write | 0.5 ms | 5 ms |
+| cold start | 24 ms | 60 ms |
+
+**Ranking is measured, not asserted.** Two labelled corpora with graded
+relevance, each containing a *control group that gets worse* when the feature
+works — so a gain cannot be manufactured by shaping the corpus:
+
+- boosts (priority, freshness, layer): MRR@10 **0.520 → 0.867** (`bench/boost-eval.ts`)
+- graph expansion to 2 hops: MRR@10 **0.193 → 0.422** (`bench/graph-eval.ts`),
+  and a query group unreachable in one hop goes 0.000 → 0.333
+
+**Caching that cannot go stale silently.** Result, embedding and hydration
+caches are invalidated by `MAX(oplog.seq)` read *from the database*, so a write
+by another process invalidates them too. A cache hit is 162–198× cheaper than a
+miss (≈25 000× for embeddings) and the ranking is bit-identical: same MRR to
+three decimals, zero rank differences.
+
+**Memory has three independent axes**, and the surface says what it hid:
+tier (project vs personal), session reach, repository reach. `prime` prints
+`N notes from other repositories hidden` rather than quietly narrowing results.
+
+**Degradation is loud.** No silent fallbacks: when the vector branch is
+unavailable the output says so and marks the answer as lexical-only; when a
+budget is exceeded it is named with the number. The invariant is that a
+degraded answer must never be indistinguishable from a healthy one.
+
+**Multi-machine sync through plain git, merged per field.** Only the oplog is
+committed. Two machines editing the same node converge: one changes title and
+priority, the other title and tags — after exchange both show the later title,
+the first machine's priority and the second's tags. Nothing is lost to
+last-writer-wins over whole records.
+
+**Migration from beads is real, not a demo.** A working project imported in
+684 ms: 796 tasks, 972 dependencies, 265 notes, 41 memories — with unknown
+issue types carried over verbatim and named, and out-of-range priorities
+clamped and named, instead of one odd row aborting the import.
+
+**Guards are proved by mutation.** Every refusal and every invariant is
+accompanied by a mutation that removes it; a guard whose removal breaks no test
+is treated as absent.
+
+## Roadmap
+
+Numbers are closed/total subtasks per milestone (`myc show <epic-id>`), as of
+2026-09-07. Done and not-done are shown the same way on purpose.
+
+| milestone | status |
+|---|---|
+| **M0** core and tasks | 30 / 33 |
+| **M0.5** self-hosting (myc developed through myc) | **4 / 4 — closed** |
+| **M1** memory | 20 / 23 |
+| **M2** semantics | 15 / 19 |
+| **M7** human interface (board, cards, threads, routing panel) | 11 / 13 |
+| **M3** code intelligence | 0 / 7 |
+| **M4** team: `myc serve`, ACL, network sync, Postgres, containers | 0 / 11 |
+| **M5** swarm self-learning: routing by cost and outcome | 0 / 12 |
+| **M6** distillation | 0 / 7 |
+
+What that means in practice: **today myc is a single-user local tool over files
+in git.** There is no server, no ACL, no team mode, and no code↔knowledge
+anchors yet. Those are designed (`docs/design/03…`, `04…`, `05…`) and tracked,
+not implemented.
+
+## Syncing between machines
+
+Only the oplog goes to git (`myc export` → `.myc/graph`, `myc import` on
+clone) — never derived projections or caches. `.myc/workspace.toml` and the
+oplog are committed deliberately; `.myc/myc.db*` and local state are not.
+
+Register the merge driver once per clone:
+
+```bash
+git config merge.myc-oplog.driver "myc merge-driver %O %A %B %L %P"
+```
+
+## License
+
+MIT — see [`LICENSE`](LICENSE). Chosen for the lowest possible friction for
+anyone embedding or forking this; every runtime dependency (Bun, ONNX Runtime,
+sqlite-vec) is permissive too.
+
+---
+
+Russian version of this document: [`docs/README.ru.md`](docs/README.ru.md).

package/bin/myc.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env bun
+/**
+ * Точка входа npm-пакета @myc/cli.
+ *
+ * Файл СОЗНАТЕЛЬНО написан на голом JS без единого `bun:`-импорта и без TS:
+ * его обязан уметь разобрать и выполнить Node. Иначе отказ выглядел бы как
+ * `Cannot find module 'bun:sqlite'` из глубины бандла — стек вместо причины
+ * (И2: деградация обязана быть громкой И понятной).
+ *
+ * Порядок важен: сначала проверка рантайма, и только потом ДИНАМИЧЕСКИЙ
+ * импорт бандла. Статический импорт Node разрешил бы до первой строки тела
+ * модуля — и мы бы снова упали на `bun:sqlite`, не успев ничего сказать.
+ */
+
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+if (typeof process.versions.bun !== "string") {
+  process.stderr.write(refusal());
+  process.exit(1);
+}
+
+// Файлы ONNX-рантайма лежат внутри пакета: JS-часть ort вшита в бандл, а .wasm
+// грузится с диска по этому пути. Явное значение пользователя не трогаем.
+const wasmDir = process.env.MYC_ORT_WASM_DIR;
+if (typeof wasmDir !== "string" || wasmDir === "") {
+  process.env.MYC_ORT_WASM_DIR = join(here, "..", "vendor", "ort");
+}
+
+// vec0 (sqlite-vec) — векторный индекс. Автопоиск в @myc/store-sqlite смотрит
+// рядом с process.execPath (у нас это bun, не пакет) и в кеш `bun install`,
+// которого при установке через npm нет. Отдаём точный путь из зависимости.
+// Явно заданный пользователем MYC_SQLITE_VEC не трогаем.
+const vecEnv = process.env.MYC_SQLITE_VEC;
+if (typeof vecEnv !== "string" || vecEnv === "") {
+  const vec = resolveVec0();
+  if (vec !== null) process.env.MYC_SQLITE_VEC = vec;
+}
+
+await import("../dist/myc.js");
+
+/**
+ * Путь к vec0 внутри платформенного пакета sqlite-vec-<os>-<arch>. null —
+ * не нашли: тогда работает штатный автопоиск, а без него myc честно скажет
+ * `vec0 не загружен` и уйдёт на BM25.
+ */
+function resolveVec0() {
+  const os = { darwin: "darwin", linux: "linux", win32: "windows" }[process.platform];
+  const ext = { darwin: "dylib", linux: "so", win32: "dll" }[process.platform];
+  const cpu = { arm64: "arm64", x64: "x64" }[process.arch];
+  if (os === undefined || cpu === undefined) return null;
+  const file = `sqlite-vec-${os}-${cpu}/vec0.${ext}`;
+  try {
+    return createRequire(import.meta.url).resolve(file);
+  } catch {
+    return null;
+  }
+}
+
+function refusal() {
+  const node = process.versions.node;
+  const lines = [
+    "",
+    "  myc requires Bun — it cannot run on Node.",
+    "",
+    `  myc запущен под Node ${node}, а он работает только на Bun: хранилище`,
+    "  построено на встроенном в Bun `bun:sqlite`, которого в Node нет.",
+    "",
+  ];
+  if (bunOnPath()) {
+    lines.push(
+      "  Bun у вас установлен — запускайте через него:",
+      "      bun x myc <команда>",
+      "  либо переустановите пакет средствами bun:",
+      "      bun add -g @myc/cli",
+      "",
+    );
+  } else {
+    lines.push(
+      "  Установите Bun (>= 1.3.0) и повторите:",
+      "      curl -fsSL https://bun.sh/install | bash        # macOS, Linux, WSL",
+      '      powershell -c "irm bun.sh/install.ps1 | iex"    # Windows',
+      "",
+      "  После установки: myc --version",
+      "",
+    );
+  }
+  return lines.join("\n");
+}
+
+/** Только для текста отказа: лишний spawn на нормальном пути не делается. */
+function bunOnPath() {
+  try {
+    const r = spawnSync("bun", ["--version"], { stdio: "ignore" });
+    return r.status === 0;
+  } catch {
+    return false;
+  }
+}

package/bin/preflight.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+/**
+ * postinstall-проверка. Запускается тем рантаймом, который ставил пакет —
+ * обычно это node, поэтому здесь снова голый JS без `bun:`.
+ *
+ * Зачем: shebang у bin/myc.js — `#!/usr/bin/env bun`, и если Bun в системе
+ * нет вовсе, первая же попытка запустить `myc` даст `env: bun: No such file
+ * or directory` (код 127) — сообщение, по которому нельзя понять ни причину,
+ * ни что делать. Наша заглушка до этого не доживает: её просто некому
+ * выполнить. Значит сказать надо здесь, на установке.
+ *
+ * Установку НЕ роняем: пакет разложен правильно, не хватает только рантайма,
+ * и это чинится `curl … | bash` без переустановки.
+ */
+
+import { spawnSync } from "node:child_process";
+
+if (typeof process.versions.bun !== "string" && !bunOnPath()) {
+  process.stderr.write(
+    [
+      "",
+      "  ┌─ @myc/cli установлен, но запускаться пока не будет ────────────┐",
+      "  │ myc работает только на Bun (хранилище на bun:sqlite).          │",
+      "  │ Bun в системе не найден.                                       │",
+      "  │                                                                │",
+      "  │   curl -fsSL https://bun.sh/install | bash                     │",
+      "  │                                                                │",
+      "  │ После этого: myc --version                                     │",
+      "  └────────────────────────────────────────────────────────────────┘",
+      "",
+    ].join("\n"),
+  );
+}
+
+function bunOnPath() {
+  try {
+    return spawnSync("bun", ["--version"], { stdio: "ignore" }).status === 0;
+  } catch {
+    return false;
+  }
+}