@lizhao1/frontal-lobe

Frontal Lobe adds repository-scoped memory to Codex and Claude Code through client-native plugin Hooks. This platform-neutral package contains the Node.js Backend, both client adapters, the bundled frontal-memory skill, local trace, and Memory Viewer. It does not proxy model-provider traffic or ship the removed workflow runtime, Gateway, or native core.

Requirements

• Node.js 20 or newer and npm.
• Python 3 for generated repository-memory operations.
• A supported Codex or Claude Code runtime for each selected client.
• A Memorax account, base user ID, API key, and network access to complete Frontal's core remote-memory configuration.

The package and local Backend/adapters can be installed without Memorax credentials, but Memorax-backed search, retrieval, and writeback remain unavailable until the account is connected.

macOS, Linux, and Windows install the same npm artifact. Frontal contains no host-specific native package, CPU selector, or Frontal-specific libc requirement. Client availability still depends on the platform. Linux supports the standalone clients and official VS Code extension runtimes; Codex App is not available on Linux. Windows deterministic gates run on GitHub-hosted Windows Server and do not replace the interactive Windows 11 x64 acceptance required for the complete user-facing support claim.

Clean-relaunch boundary

This package is not an in-place upgrade from @ch4acko3/frontal-lobe. Before installing:

1. Use the old package to run frontal uninstall.
2. Restore any Codex or Claude provider still pointing at Frontal with the old release or a trusted client-owned profile/backup.
3. Uninstall the old npm package.
4. Archive the old $FRONTAL_HOME or select a new unused home.

The current package does not migrate or delete old Gateway/provider state. Do not install over that state with --force.

Install

npm install -g @lizhao1/frontal-lobe --foreground-scripts

Keep --foreground-scripts so npm displays setup prompts, Backend status, and client restart guidance.

For a trusted local package:

npm install -g ./lizhao1-frontal-lobe-0.0.9.tgz \
  --force \
  --foreground-scripts

Use --force only for deliberate local-package replacement, not to cross the clean-relaunch boundary.

Postinstall

Postinstall detects runnable Codex and Claude Code clients and enables every detected integration independently. It does not ask an all/codex/claude selection question. The detected set is persisted in $FRONTAL_HOME/config.toml; an absent client is skipped without blocking the other client or the shared Backend.

Interactive setup asks only whether to connect the Memorax account required by Frontal memory and, when Codex is detected, whether to activate and trust its Hooks. Postinstall starts the Backend and runs frontal status. Read the final status: npm installation can finish even when a detected adapter needs attention.

Updates preserve the existing [clients] intent. A selected client that has since been uninstalled is skipped for that update, while remaining clients and the Backend continue; a transient failed probe does not erase the persisted selection.

Before accepting a Memorax base user ID and API key, postinstall discloses that trusted repository sessions automatically send selected user prompts and final assistant answers to Memorax after replies. Entering both values completes core memory enablement; there is no second writeback question. Generated configuration enables automatic writeback by default.

Skipping the connection, exhausting scripted answers, or running a non-interactive first install leaves a truthful partial state: Package installed, Memorax not configured. Existing valid file or environment credentials are still recognized.

Codex setup accepts a standalone CLI, Codex App's bundled runtime, or the official VS Code extension runtime. Claude setup accepts a standalone CLI or the official VS Code extension runtime. Remote SSH, WSL, and Dev Container users must install Frontal in the same remote environment as the extension runtime.

Frontal never asks for, reads, or rewrites client provider credentials, provider URLs, models, or login modes. Codex official/API login and Claude built-in/API-provider profiles use the same client-specific Hooks while provider traffic remains client-owned.

If npm scripts were disabled or Codex activation was skipped:

frontal codex-plugin install
frontal codex-plugin activate --yes

Restart or refresh selected clients after installation.

Use

frontal --version
frontal start
frontal status
frontal-codex status
frontal-claude status
frontal memory status

The Backend defaults to loopback. It hosts memory, lifecycle, trace, and Viewer surfaces; it does not expose OpenAI Responses or Anthropic Messages provider routes.

Client trace files remain under the local $FRONTAL_HOME. The package has no export command or outbound transport for retained trace data. Documented Memorax queries and writeback send memory-operation content, but not the retained trace artifact or its local-path provenance.

Generated config enables exact-transcript automatic writeback. Automatic retrieval remains disabled until [memory.overlay].enabled = true. Active search/add is available through the bundled $frontal-memory skill or:

frontal memory search --query "..."
frontal memory add --memory "..." --type "..." --reason "..."

All real Memorax operations derive a repository-scoped identity from the configured base user ID. Missing credentials, unavailable scope, transcript mismatch, or invalid content fails closed and does not alter provider traffic. Set [memory.writeback].enabled = false to disable automatic writeback durably, or FRONTAL_MEMORAX_WRITEBACK_ENABLED=false as the global kill switch.

Override the persisted client selection for one lifecycle command:

frontal start --clients claude
frontal stop --clients codex
frontal uninstall --clients codex

A partial stop/uninstall preserves the Backend and npm package while another managed client remains active.

Installed documentation

The package includes a self-contained documentation set:

• docs/architecture.md
• docs/configuration.md
• docs/install.md
• docs/memory.md
• docs/security-model.md
• docs/testing.md
• docs/troubleshooting.md
• docs/adr/README.md
• docs/adr/0018-client-owned-provider-boundary.md
• docs/adr/0019-client-transcript-writeback-authority.md
• docs/adr/0020-repository-scoped-memory-identity.md
• docs/adr/0021-stable-hook-runtime-generations.md
• docs/adr/template.md

The package also includes examples/memory.env.example as a local, untracked environment template. Canonical field names and defaults remain in docs/configuration.md.

Update

Updates inside this package line use:

frontal update

Stable installs follow latest; prereleases follow preview. Override or repair explicitly:

frontal update --latest
frontal update --preview
frontal update --force
frontal update --home /absolute/path/to/frontal-home

During npm preinstall, an existing managed Backend is stopped without disabling the client integrations. Package setup fails if PID ownership cleanup cannot be confirmed. If scripts are explicitly disabled, run frontal stop --clients none before an in-place update.

npm may unpack replacement package files before it invokes the replacement package's preinstall script. Automated retirement is therefore guaranteed before new postinstall setup, not before the first package file is replaced. For a 0.0.2 migration that requires the stronger boundary, stop Frontal explicitly before starting npm.

--home selects the exact managed Backend and passes that absolute home through the npm lifecycle. A direct npm install -g update cannot discover arbitrary custom homes; export the same absolute FRONTAL_HOME before invoking npm.

Updates preserve config and provider ownership, refresh Backend/plugin assets, and do not rerun first-install questions. New or changed Codex Hook hashes require review; use frontal codex-plugin trust-hooks if an interactive authorization step was skipped.

For a runtime-only update with the same stable plugin shell, an in-flight exact turn completes on its pinned Hook generation and the same session's next user prompt selects the new generation without a client restart. The first update from the pre-generation 0.0.7 cache, or a later shell/plugin contract change, still requires one client refresh. This does not make Backend replacement zero-downtime: preinstall still stops the managed Backend before postinstall.

Uninstall

Run Frontal cleanup before removing package files:

frontal uninstall

A full uninstall stops the Backend, disables managed Hooks, removes managed client plugin registrations, and removes the global npm package. It leaves client provider settings, $FRONTAL_HOME, and Claude plugin data unchanged.

Do not start with npm uninstall: modern npm does not run an uninstall lifecycle script, so the Frontal commands disappear before they can report complete cleanup. The Backend package-removal watchdog is only a safety net. If a successful full lifecycle uninstall leaves the npm entry behind, then run:

npm uninstall -g @lizhao1/frontal-lobe