@vortex-os/base

 __   __       _   _____  __
 \ \ / ___ _ _| |_| __\ \/ /
  \ V / _ | '_|  _| _| >  <
   \_/\___|_|  \__|___/_/\_\
  Vortex absorbs context · EX executes it

Base entry point for VortEX — a Multi-Agent Personal AI Work OS framework.

@vortex-os/base bundles the framework's 14 internal workspaces (core utilities, slash-command runtime, memory store, daily-log store, decision-log store, runbook store, link-rewriter, index-generator, data-linter, report-generator, two catalog modules, the proactive-curator proposal engine, and the session-rituals plugin) into a single installable package. Install once, get the whole framework.

Install

Install the framework, plus the optional @vortex-os/memory-extended add-on for semantic recall (drop it if you don't want search):

npm install @vortex-os/base @vortex-os/memory-extended

On Windows PowerShell? If npm fails with a script-execution / UnauthorizedAccess error, that's PowerShell's default policy blocking npm's wrapper script — not a VortEX problem (it blocks every npm command). Fix it one of these ways: run npm.cmd install … instead of npm install …, or use cmd.exe, or enable scripts once with Set-ExecutionPolicy -Scope CurrentUser RemoteSigned -Force and retry.

Quick start

@vortex-os/base ships a vortex CLI. Two ways to a working instance:

Easiest — let your agent do it. In a new folder, open your coding agent (Claude Code, Codex, …) and tell it — keep the literal vortex init, don't translate or paraphrase it: "install @vortex-os/base and @vortex-os/memory-extended, then run vortex init." (Before the rule files exist the agent has no VortEX context, so a paraphrase like "initialize vortex" can be misread as a generic project setup; the exact vortex init avoids that.) The agent installs the packages and runs init (which asks for your name and role; what you're working on is optional). Then restart the agent in that folder so it loads the freshly created rule files (CLAUDE.md, AGENTS.md, …) and session hooks — agents read those only at startup. Bonus: the agent runs npm in its own shell, so the Windows PowerShell issue above never comes up.

Manual — three steps:

npm install @vortex-os/base @vortex-os/memory-extended   # framework + semantic-recall add-on
npx vortex init                                          # scaffold the instance (asks name + role; task optional)
# then open your agent (e.g. `claude`) in that folder — a fresh start loads the rules init just created

npx vortex init is non-destructive and creates, in the current folder:

• 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 vortex session-start / … session-end (the --no-install flag makes the auto-firing hook fail closed rather than install on a cache miss; resolving the bare vortex bin — local node_modules/.bin first, then PATH — lets the global-setup hook fire from any folder, not only where a local install exists), 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:

npx vortex init --name "Alex" --role "engineer" --task "set up my work notes"

Other CLI entry points (all run base-only — /recall lights up only when the optional add-on is installed):

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

import {
  core,
  slashCommands,
  memorySystem,
  worklog,
  decisionLog,
  proactiveCurator,
  sessionRituals,
} from "@vortex-os/base";

// Use the slash-rituals registry against your own data directory
const registry = sessionRituals.createRitualRegistry();
const ctx = core.makeContext(process.cwd());

await slashCommands.runSlash("/session-start", { registry, context: ctx });

Opt-in /curate surface

The /curate command is opt-in because it needs a host-supplied LLM adapter. To enable it on Claude Code, wire a sub-agent invoker:

import { proactiveCurator, sessionRituals } from "@vortex-os/base";

const llm = new proactiveCurator.ClaudeCodeLLMJudge(async ({ prompt }) => {
  // Host-specific sub-agent invocation; return the sub-agent's raw answer.
  return await invokeMySubAgent(prompt);
});

const registry = sessionRituals.createRitualRegistry({
  curate: {
    llm,
    // Optional — supply the in-session insight surface with recent turns.
    insightInputProvider: () => ({
      recentTurns: myTurnBuffer.recent(20),
      accumulatedTokens: myTurnBuffer.tokenCount(),
    }),
  },
});

Without an LLMJudge, /curate is simply absent (graceful degradation); the rest of the rituals work unchanged.

Exported namespaces

Each internal workspace is exposed as a top-level namespace on the package:

| Namespace | Source workspace | Role | |---|---|---| | core | @vortex-os/core | Frontmatter parser (BOM-safe), three-tier privacy filter, ModuleContext path resolver, shared types | | slashCommands | @vortex-os/slash-commands | Command, CommandRegistry, runSlash primitives | | memorySystem | @vortex-os/memory-system | Markdown-frontmatter memory store + MEMORY.md index writer + diff helpers | | dataLint | @vortex-os/data-lint | Pluggable linter for markdown directories (frontmatter / privacy / wiki-link checks) | | aiCodingPitfalls | @vortex-os/ai-coding-pitfalls | Typed catalog of AI coding pitfall patterns | | toolRules | @vortex-os/tool-rules | Typed catalog of tool usage rules | | reportGenerator | @vortex-os/report-generator | HTML reports with privacy-marker section filtering | | worklog | @vortex-os/worklog | Daily work-log store with year/month layout | | decisionLog | @vortex-os/decision-log | Decision-log store with template-driven entry creation | | indexGenerator | @vortex-os/index-generator | _INDEX.md rendering (flat + nested modes) | | runbooks | @vortex-os/runbooks | Runbook store with last_tested-based stale detection | | linkRewriter | @vortex-os/link-rewriter | Wiki-link extract / resolve / check / rewrite | | 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, /log, /handoff, /decision, /agenda, /reindex, /resume, /vortex, /curate, /recall |

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 — 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.
• @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>.
• 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

• Bundled: all 14 workspaces are bundled into the published artifact via tsup. Consumers do not need to install workspace packages individually.
• External dependency: yaml is left as a runtime dependency (npm resolves it on install).
• Format: ESM only. "type": "module" in your consumer is required (or set up .mjs).
• Types: a single dist/index.d.ts exposes all namespace types.

Related

• VortEX framework repository — source, design docs, integration template for instances
• Capability-cluster packaging design — how the framework splits into installable clusters
• Memory-extended design — memory-extended add-on design reference

License

MIT — see LICENSE.