@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), the write-guard hook (vortex guard write — denies literal control bytes in file writes; remove its PreToolUse group to opt out), 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      # no-op (kept for hook compatibility; gap handling is at session-start)
npx vortex doctor           # health diagnosis
npx vortex update           # refresh framework templates (never clobbers your edits)
npx vortex statusline       # Claude Code status-bar renderer (see below)
npx vortex failure          # failure ledger: record / list (the self-improvement loop)
npx vortex source-map       # queryable map of your own source code: index / find / add-target / note / stats

Self-improvement loop (failure ledger)

Rules saved in data/_memory/ are loaded at session start — but at action time the model's attention is on the task, and a registered rule can still slip. VortEX therefore counts: when the agent's own failure becomes visible (you correct it, a test disproves it, a cross-check catches it), the agent records it with vortex failure record --key <root-cause-key> --what "<one line>" into data/_failures/ (append-only, one file per occurrence). Recurrence is machine-counted per key and escalates on a ladder:

1. 1st occurrence — recorded.
2. 2nd, while a rule already covers it — that rule's write-time gate becomes mandatory.
3. 3rd+ — the agent must propose a deterministic defense (a hook, a pre-commit check, a wrapper) — proposals only, nothing self-installs.

A guard_denied entry — an installed guard blocking the mistake — stays visible in the counts (shown as ×N (+M guard-blocked)) but no longer drives the ladder: escalation runs on unblocked occurrences only, so a working defense doesn't re-trigger "propose a defense" for the class it already covers.

The session-start report surfaces recurring keys automatically, and promoting a lesson into _memory/ requires evidence links, a replay check ("would this rule have prevented the recorded cases?") and your approval. Disable with autoRecord.failures: false in .agent/vortex.json.

Guards ship in the box — vortex init wires them as Claude Code hooks:

• vortex guard write (PreToolUse) denies file writes containing literal control bytes (escape notation always works instead) — a denial also records itself into the ledger.
• vortex guard risky-action (PreToolUse/Bash) turns npm/pnpm/yarn publish and git push into a user-confirmation prompt carrying the instance's related failure-ledger counts plus a checklist — it asks, never denies. With the @vortex-os/ontos add-on installed, the prompt also reads the knowledge graph and says "this failure class recurred ×N — covering rule: X / defense: Y", so accumulated lessons are consumed at the decision point (read-only, best-effort; absent add-on changes nothing). Turn a rule off with guards.publishAsk / guards.pushAsk: false, the graph lines with guards.graphContext: false, in .agent/vortex.json.
• vortex guard memory-router (UserPromptSubmit) spots a decision-why / recurrence-why / past-record question and nudges the agent to ground the answer in your records (decision chain, failure ledger, /recall) before replying.

All are fail-open (a guard bug never blocks your work) and opt-out by removing their hook group in .claude/settings.json.

Source map (your code, queryable)

"Does my X do Y? Where is it implemented?" should be an indexed lookup, not a fresh grep — or worse, an unverified assertion. vortex source-map index scans the repos listed in .agent/vortex.json → sourceMap.targets (zero-config default: the instance's own code folders) into a disposable, machine-local SQLite index (data/_indexes/source-map.sqlite; needs Node ≥ 22.5 for the built-in sqlite — older runtimes get a clear error and nothing else is affected). Generic columns (solution · system · feature · kind) let one DB serve many programs; every row carries file:line, the signature, and the preceding doc comment as a primary-source pointer.

• find <term> answers from the index (--json for agents) and marks stale targets; freshness is automatic — each target's git HEAD is fingerprinted at index time, and find/session-start kick a detached background reindex when the code moved.
• add-target <repo-root> registers a repo mechanically (atomic write, dedup) — agents propose it the moment code work touches an unmapped repo.
• note --feature --claim records a capability answer the agent just verified from code into a separate overlay DB, stamped with the repo fingerprint and marked STALE once the code moves — LLM output never lands in the canonical index.

The regex indexer is an honest 80%: a symbol it misses is still a grep away, and an important claim still closes by reading the pointed-at file.

Claude Code status bar (on by default)

vortex statusline renders a colored status bar for Claude Code's statusLine setting — model + a reasoning-effort meter (one bar whose height/color encode low→ultracode), a context-window gauge with used/total tokens, a clock, session cost, the 5-hour/7-day rate-limit gauges with time-to-reset, cache hit-rate, project + git branch/commit, session duration, lines changed, the number of open Claude Code sessions (best-effort process count) — and, inside a VortEX instance, the framework version and the latest worklog file:

🧠 Fable 5 │ █ max │ █░░░░░░░░░ 12% · 120K/1M │ 🕐 22:25 │ 💰 $9.22
5h ██████░░ 75%(1h9m) │ 7d ███████░ 96%(7h30m) │ 📦 cache 99%
📁 my-project │ ⎇ main 2b0949d │ ⏱ 1h26m │ +90 -49 │ ⧉ 1
🌀 VortEX │ last: 2026-06-10_0452-notes.md

The bar is wired automatically by vortex init (new instances) and vortex update (existing instances) — merge-safe: a bar you already configured is kept untouched, and it is offered only once (delete the statusLine entry from .claude/settings.json and it stays deleted). To wire it by hand, switch forms, or replace a foreign bar:

npx vortex statusline install          # full bar (4 lines inside an instance, 3 outside)
npx vortex statusline install --lite   # compact 1-line bar
npx vortex statusline install --force  # replace a non-VortEX bar explicitly

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.