@vortex-os/base 0.4.0 → 0.5.0

package/README.md

@@ -30,11 +30,13 @@ npx vortex init                 # scaffold the instance (asks for name / role /
 
 `npx vortex init` is non-destructive and creates, in the current folder:
 
-- the five per-agent router files — `AGENT.md`, `CLAUDE.md`, `CODEX.md`, `GEMINI.md`, `.cursorrules` — so any agent host finds VortEX's behavior contract (these are generic templates you personalize over time);
+- the per-agent files — `AGENTS.md` (the thin Codex-CLI entry, auto-loaded by Codex and other `AGENTS.md`-aware tools) plus thin routers `CLAUDE.md`, `GEMINI.md`, `.cursorrules`, all pointing at `AI-RULES.md` (the single source of truth for shared rules) — so any agent host finds VortEX's behavior contract (these are generic templates you personalize over time);
 - the `data/` skeleton (`_memory/`, `worklog/`, `decision-log/`, `runbooks/`, `hubs/`, `inbox/`), your user-profile memory, and today's first worklog;
 - `.claude/settings.json` with the session hooks wired as `npx --no-install -p @vortex-os/base vortex session-start` / `… session-end` (the `--no-install` flag and explicit `-p` package make the auto-firing hook fail closed rather than install or shadow), plus the agent-mediated slash-commands in `.claude/commands/`;
 - `.agent/vortex.json` (auto-record config) and a minimal `package.json` with `"type":"module"` if none exists.
 
+`vortex import --from <folder>` brings an existing notes folder in — markdown is auto-classified (worklog / decision-log / …) and **attachments (PDFs, images, …) are copied byte-for-byte** into the same layout; credential files (`*.key`, `.env`, `secrets/` …) and oversized files are skipped and reported. As the framework improves, `vortex update` refreshes the installed templates **without ever overwriting a file you edited** (your edit is parked at `<file>.new`); `vortex doctor` checks instance health.
+
 Pass the answers inline to skip the prompts:
 
 ```bash
@@ -46,9 +48,11 @@ Other CLI entry points (all run base-only — `/recall` lights up only when the
 ```bash
 npx vortex --list           # list available commands
 npx vortex status           # instance state report
+npx vortex import --from X  # bring an existing notes folder into data/
 npx vortex session-start    # start-of-session boot report (git pull + counts + catch-up)
 npx vortex session-end      # worklog safety net
 npx vortex doctor           # health diagnosis
+npx vortex update           # refresh framework templates (never clobbers your edits)
 ```
 
 ## Library usage
@@ -118,20 +122,20 @@ Each internal workspace is exposed as a top-level namespace on the package:
 | `proactiveCurator` | `@vortex-os/proactive-curator` | Topic-aware proposal engine — in-session insight capture + hub auto-curation with 4-action active placement (`create-folder` / `create-file` / `append-section` / `update-file`). Asymmetric LLM gate for hub thresholds (3 weak / 5 strong). Decline durability + Claude Code `LLMJudge` adapter. |
 | `sessionRituals` | `@vortex-os/session-rituals` | Daily session-loop slash commands: `/session-start`, `/reindex`, `/decision`, `/log`, `/vortex`, `/curate`, `/recall` |
 
-## Capability add-ons (Phase 11+)
+## Capability add-ons
 
 Future capability clusters publish as siblings under the `@vortex-os` scope and install alongside the base. The base auto-detects installed add-ons at session-start:
 
-- **`@vortex-os/memory-extended@0.5.0` (Phase 11) — shipped** — all five namespaces are live: `sqlite` (structured index + drift detection), `vector` (brute-force cosine backend, local `multilingual-e5-small` embedder), `recall` (two-stage hybrid `/recall` over memories *and* conversation sessions), `sessionArchive` (four first-party host adapters: Claude Code, Codex, Gemini, Claude Desktop), `consolidate` (post-session memory-candidate proposer). Peer-depends on this base. See [memory-extended-design.md](https://github.com/vortex-os-project/vortex/blob/main/docs/memory-extended-design.md).
-- `@vortex-os/dev-toolkit` (Phase 12) — vibe coding + self-QA + CI/CD assistance.
-- `@vortex-os/vision` (Phase 14, under review) — screen context + visual reasoning.
+- **`@vortex-os/memory-extended` — shipped** — six namespaces are live: `sqlite` (structured index + drift detection), `vector` (brute-force cosine backend, local `multilingual-e5-small` embedder), `recall` (two-stage hybrid `/recall` over memories *and* conversation sessions), `sessionArchive` (four first-party host adapters: Claude Code, Codex, Gemini, Claude Desktop), `consolidate` (post-session memory-candidate proposer), and `mcp` (an MCP server, `vortex-mcp-recall`, exposing memory tools over stdio). Peer-depends on this base. See [memory-extended-design.md](https://github.com/vortex-os-project/vortex/blob/main/docs/memory-extended-design.md).
+- `@vortex-os/dev-toolkit` (planned) — vibe coding + self-QA + CI/CD assistance.
+- `@vortex-os/vision` (under consideration) — screen context + visual reasoning.
 
 Each add-on installs alongside the base and extends what the agent can do without forcing a base upgrade.
 
 ## Privacy & network behavior
 
 - **`vortex init` folder scan.** To suggest content you might want to import, `init` does a read-only scan for common notes-folder names (e.g. an Obsidian vault, a `notes/` directory) under your home directory. It only reads directory listings to count Markdown files and surface a hint — it never copies, modifies, or transmits anything. Import happens only when you explicitly run `vortex import --from <path>`.
-- **No network calls in the base.** Base itself makes no outbound network requests. The optional `@vortex-os/memory-extended` add-on, when installed, may download an embedding model (read-only `GET` from `huggingface.co`, cacheable / offline-able via `HF_HUB_OFFLINE=1`) and feeds transcript excerpts to whatever LLM adapter you wire into its consolidation step. See that package's README for details.
+- **One optional update check.** By default base runs a single npm-registry version check once per session at session start (`npm view @vortex-os/base version`) to tell you whether a newer version is published — nothing is installed automatically. Offline → silent skip; disable entirely with `updates: { check: "off" }` in `.agent/vortex.json`. Base makes no other outbound network requests. With the optional `@vortex-os/memory-extended` add-on installed, base sets semantic recall up the first time by downloading an embedding model (~470 MB once, read-only `GET` from `huggingface.co`) — in the **background**, so it never blocks session start. This is on by default (installing the add-on is the opt-in); to keep that download manual on a metered line or in CI, set `autoRecord.vectorizeAutoDownload: false` in `.agent/vortex.json` (or env `VORTEX_VECTORIZE_AUTO_DOWNLOAD=0`) and set it up yourself with `vortex vectorize` / `/recall`. The model is cacheable / offline-able via `HF_HUB_OFFLINE=1`. The add-on also feeds transcript excerpts to whatever LLM adapter you wire into its consolidation step. See that package's README for details.
 
 ## Packaging notes
 
@@ -143,8 +147,8 @@ Each add-on installs alongside the base and extends what the agent can do withou
 ## Related
 
 - [VortEX framework repository](https://github.com/vortex-os-project/vortex) — source, design docs, integration template for instances
-- [Phase 10 split plan v2](https://github.com/vortex-os-project/vortex/blob/main/docs/phase-10-split-plan.md) — capability-cluster packaging design
-- [Memory-extended design](https://github.com/vortex-os-project/vortex/blob/main/docs/memory-extended-design.md) — Phase 11 (memory-extended add-on) reference
+- [Capability-cluster packaging design](https://github.com/vortex-os-project/vortex/blob/main/docs/phase-10-split-plan.md) — how the framework splits into installable clusters
+- [Memory-extended design](https://github.com/vortex-os-project/vortex/blob/main/docs/memory-extended-design.md) — memory-extended add-on design reference
 
 ## License
 

package/dist/catch-up-GDDKPZHJ.js

@@ -0,0 +1,8 @@
+import {
+  catchUpSessions
+} from "./chunk-3L5DLEGP.js";
+import "./chunk-PZ5AY32C.js";
+export {
+  catchUpSessions
+};
+//# sourceMappingURL=catch-up-GDDKPZHJ.js.map

package/dist/{chunk-6SO4DAWJ.js → chunk-3L5DLEGP.js}

@@ -1,15 +1,13 @@
-var __defProp = Object.defineProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-
 // ../plugins/session-rituals/dist/catch-up.js
 async function catchUpSessions(ctx, opts) {
   const { sessionArchive } = await import("@vortex-os/memory-extended");
   const dataDir = ctx.dataDir;
   const cwd = opts?.cwd ?? ctx.repoRoot;
-  const adapters = opts?.adapters ?? [sessionArchive.claudeCodeAdapter];
+  const adapters = opts?.adapters ?? [
+    sessionArchive.claudeCodeAdapter,
+    sessionArchive.codexAdapter,
+    sessionArchive.geminiAdapter
+  ];
   const ingestResult = await sessionArchive.ingest({ adapters, dataDir, cwd, env: opts?.env });
   const store = new sessionArchive.SessionArchiveStore(dataDir);
   let indexedPulled = 0;
@@ -26,7 +24,6 @@ async function catchUpSessions(ctx, opts) {
 }
 
 export {
-  __export,
   catchUpSessions
 };
-//# sourceMappingURL=chunk-6SO4DAWJ.js.map
+//# sourceMappingURL=chunk-3L5DLEGP.js.map

package/dist/chunk-3L5DLEGP.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../plugins/session-rituals/src/catch-up.ts"],"sourcesContent":["import type { ModuleContext } from \"@vortex-os/core\";\n// Type-only — erased at compile time, so importing it does NOT pull the\n// `@vortex-os/memory-extended` add-on (or its native sqlite/level deps) into\n// the module graph of consumers that only need the types. The runtime engine\n// is loaded lazily inside the function body via `await import(...)`.\nimport type { sessionArchive } from \"@vortex-os/memory-extended\";\n\n/**\n * Start-of-session \"catch-up\": fold conversation transcripts into the local\n * search archive without the user ever having to wrap up a session.\n *\n * Two sources, one pass:\n *  - **local (a)** — this machine's own transcripts that are not archived yet,\n *    read from every detected agent host's transcript store (Claude Code,\n *    Codex, Gemini) and scoped to the current project. Because all hosts are\n *    swept on every start, a single Claude Code session-start also folds in the\n *    Codex/Gemini sessions you ran in the same project, into one archive.\n *  - **pulled (b)** — transcripts created on another machine that arrived as\n *    normalized text via git sync. Their text is present but this machine's\n *    DB (local, derived, gitignored) has never indexed them.\n *\n * Text only — vectorization is deferred to recall/rebuild so session start\n * stays fast. The whole step is gated by `autoRecord.archive` at the call site\n * and is best-effort: callers should treat a thrown archive backend (e.g. the\n * native sqlite module not built) as \"skip\", never as a fatal start error.\n */\nexport interface CatchUpResult {\n  /** Local transcripts newly archived this run (source a). */\n  readonly ingestedLocal: number;\n  /** Normalized transcripts from another machine newly indexed (source b). */\n  readonly indexedPulled: number;\n  /** Per-session ingest errors (source a). */\n  readonly errors: number;\n}\n\nexport interface CatchUpOptions {\n  /** Restrict local ingest to one project's transcripts. Default: `ctx.repoRoot`. */\n  readonly cwd?: string;\n  /**\n   * Transcript adapters for local ingest. Default: all CLI hosts — Claude Code,\n   * Codex, and Gemini. Each adapter's `detect()` returns false when its host is\n   * absent, so registering all three is ~free on a machine that only uses one.\n   * (Claude Desktop is opt-in — it needs the `classic-level` dependency — so it\n   * is not in the default set; a caller can add it.) Tests inject fakes (or a\n   * sandbox `env.home`) so the scan never touches the real home directory.\n   */\n  readonly adapters?: sessionArchive.IngestParams[\"adapters\"];\n  /** Adapter environment override (e.g. a sandbox HOME). Tests use this. */\n  readonly env?: sessionArchive.IngestParams[\"env\"];\n}\n\nexport async function catchUpSessions(\n  ctx: ModuleContext,\n  opts?: CatchUpOptions,\n): Promise<CatchUpResult> {\n  // Lazy-load the optional add-on. Base ships without `memory-extended`; this\n  // import resolves only when the add-on is installed alongside it. The call\n  // site already gates this step on `autoRecord.archive` and treats a thrown\n  // backend as \"skip\", so a missing add-on surfaces as a normal load error\n  // the caller can catch.\n  const { sessionArchive } = await import(\"@vortex-os/memory-extended\");\n\n  const dataDir = ctx.dataDir;\n  const cwd = opts?.cwd ?? ctx.repoRoot;\n  const adapters = opts?.adapters ?? [\n    sessionArchive.claudeCodeAdapter,\n    sessionArchive.codexAdapter,\n    sessionArchive.geminiAdapter,\n  ];\n\n  // (a) Ingest this machine's not-yet-archived transcripts for the current\n  // project. Writes the normalized copy into the archive (which git syncs) and\n  // a local DB row. Text only — no vectorization here.\n  const ingestResult = await sessionArchive.ingest({ adapters, dataDir, cwd, env: opts?.env });\n\n  // (b) Index normalized transcripts that arrived from another machine via git\n  // pull — their text is on disk but this machine's DB has no row yet.\n  const store = new sessionArchive.SessionArchiveStore(dataDir);\n  let indexedPulled = 0;\n  try {\n    indexedPulled = store.reindexFromNormalized().indexed;\n  } finally {\n    store.close();\n  }\n\n  return {\n    ingestedLocal: ingestResult.sessionsIngested,\n    indexedPulled,\n    errors: ingestResult.errors.length,\n  };\n}\n"],"mappings":";AAmDA,eAAsB,gBACpB,KACA,MAAqB;AAOrB,QAAM,EAAE,eAAc,IAAK,MAAM,OAAO,4BAA4B;AAEpE,QAAM,UAAU,IAAI;AACpB,QAAM,MAAM,MAAM,OAAO,IAAI;AAC7B,QAAM,WAAW,MAAM,YAAY;IACjC,eAAe;IACf,eAAe;IACf,eAAe;;AAMjB,QAAM,eAAe,MAAM,eAAe,OAAO,EAAE,UAAU,SAAS,KAAK,KAAK,MAAM,IAAG,CAAE;AAI3F,QAAM,QAAQ,IAAI,eAAe,oBAAoB,OAAO;AAC5D,MAAI,gBAAgB;AACpB,MAAI;AACF,oBAAgB,MAAM,sBAAqB,EAAG;EAChD;AACE,UAAM,MAAK;EACb;AAEA,SAAO;IACL,eAAe,aAAa;IAC5B;IACA,QAAQ,aAAa,OAAO;;AAEhC;","names":[]}

package/dist/chunk-PZ5AY32C.js

@@ -0,0 +1,10 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+export {
+  __export
+};
+//# sourceMappingURL=chunk-PZ5AY32C.js.map

package/dist/chunk-PZ5AY32C.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}