Hyperconsciousness

Hyperconsciousness (hc)

HC is an encrypted, append-only knowledge store for humans and agents. It keeps signed records in sync across devices. You choose what an agent can access and for how long through scoped, expiring grants.

The repository contains the Rust engine, CLI, MCP/HTTP server, and agent skills, along with the optional local dashboard described below. Desktop, iOS, Android, and mobile web apps are outside its scope. Private Companion and agent orchestration are maintained separately.

HC is a developer alpha, so APIs and commands may change. No independent security audit is claimed. Read the security limits before using it for important data. The package is hyperconsciousness; run it with hc.

Install

On macOS or Linux, install the latest published alpha with one command:

curl -fsSL https://raw.githubusercontent.com/louis030195/hyperconsciousness/main/install.sh | sh

The installer verifies the release checksum and version before installing to ~/.local/bin. It does not create a brain or start a service. Follow its PATH instruction if needed. GitHub releases include Apple Silicon/Intel Mac, Linux x86-64/ARM64 and Windows x86-64 builds. Linux builds require Ubuntu 24.04-compatible libraries; Mac builds are not notarized. On Windows, extract the ZIP and run hc.exe.

Installer-managed copies update automatically from GitHub releases. On use, HC checks in the background at most once every six hours. Running commands and MCP sessions keep their current binary; the next launch uses the update. No dashboard or persistent updater service starts. Windows ZIP users can opt in with hc update --enable.

Use hc update to update now, hc update --check to check without installing, or hc update --disable to turn it off. HC_AUTO_UPDATE=0 skips automatic checks for that process. Source/Cargo/npm builds and installs pinned with HC_VERSION do not opt in automatically. See update behavior.

To connect to an existing organization, use its connection pack:

hc setup company-hc.json --codex
hc login
hc status --remote

Setup installs the supplied instruction skills and registers HC with Codex. Start a new Codex task after signing in. No Bun or provider API keys are needed. See hosted access for other clients and access boundaries. The company connection is separate from your personal brain.

Ingest chats and tools

The ingestion skill catalog includes Codex and Claude chats, Slack, Google Workspace, GitHub, CRM, support, documents, meetings, analytics, ads, billing, marketing and cloud operations. Install all recipes from a clone:

python3 scripts/install-ingestion-skills.py --dest ~/.codex/skills

For Claude Code, use --dest ~/.claude/skills. These are portable agent instructions using existing source access and an authorized HC writer. They preserve source identity, freshness and retry receipts. Installing skills does not connect accounts or start background ingestion; the catalog explains selection, prerequisites and verification.

Local dashboard

Use the optional HC Atlas dashboard to inspect storage, file metadata, identity, grants, and configured peers. You can navigate with the keyboard or use its command menu. The UI guide and screenshots show each view. With an existing authenticated HC reader configured, Records also lets you search notes and imported source records, page through older results, and open text previews.

The dashboard runs locally and requires an existing HC installation. Install it separately from the CLI. Agents can start it when a visual inspection would help; the agent startup notes explain how.

Check the prerequisites, then run these commands from the repository root:

cd dashboard
bun install --frozen-lockfile
bun run build
bun run start

Open http://127.0.0.1:3217, or reuse the dashboard there if it is already running. Its server keeps running when you close the browser and stops when you end the server process. Startup is manual: HC setup and CLI commands do not launch the dashboard or open a browser. The dashboard inspects local metadata; it does not provide hosted team access.

Install from source

Install Rust with rustup. This checkout pins Rust 1.88.0. Linux builds also need native headers; on Ubuntu or Debian, install them with:

sudo apt-get install build-essential pkg-config libssl-dev libdbus-1-dev

Build the source on macOS or Linux:

git clone https://github.com/louis030195/hyperconsciousness.git
cd hyperconsciousness
cargo build --release --locked
mkdir -p "$HOME/.local/bin"
install -m 755 target/release/hc "$HOME/.local/bin/hc"
export PATH="$HOME/.local/bin:$PATH"
hc --help

On Windows, use cargo build --release --locked and run target\release\hc.exe. Add the binary's directory to your PATH if needed.

The npm registry package is not the distribution source for this alpha. Use the verified binaries above or build this checkout. npm packaging remains tested for compatibility. See release automation.

Try an isolated store

Try HC in a new directory. Passing that directory to every command keeps this example separate from an existing personal store:

HC_STORE="$PWD/hc-demo"
hc start --dir "$HC_STORE"
hc write "A demo note" --tags demo --sensitivity normal --dir "$HC_STORE"
hc read --dir "$HC_STORE"
hc status --dir "$HC_STORE"

hc read displays local records without a full integrity check. It can display a record whose signature was modified, and it can exit successfully after withholding a record whose ciphertext was modified. Grant-scoped MCP reads verify history and reject those mutations. To validate backups, use the documented recovery verification and drill workflow.

Give an agent limited access

For an agent running on the same trusted node, grant access to that node's device identity. This example allows one day of read-only access to normal notes tagged demo:

HC_DEVICE="$(hc id --dir "$HC_STORE" | cut -d: -f2)"
hc grant "$HC_DEVICE" --kinds note --tags demo \
  --sensitivity normal --days 1 --dir "$HC_STORE"
hc grants --dir "$HC_STORE"

Copy the grant id into your MCP client configuration. Use absolute paths for your HC executable and the store you chose:

{
  "mcpServers": {
    "hc": {
      "command": "/absolute/path/to/hc",
      "args": ["mcp", "--as", "<grant-id>", "--dir", "/absolute/path/to/hc-demo"]
    }
  }
}

MCP search supports an opt-in lexical relevance mode for multiword queries. Literal search and chronological pagination remain the default. Relevance mode requires no model or external service.

MCP exposes overview, request_access, access_status, search, recent, record, remember, remember_many, use_secret, and files. A tool's presence does not grant permission to use it. Add --write only when the agent needs capture access. Credential operations require a separate USE grant and a signed device request. For company members, groups, multiple devices and agents, use company gateway access. Company mode checks current membership on every tool call and requires client-side request signing.

hc revoke <grant-id> --dir "$HC_STORE"
hc audit --dir "$HC_STORE"

Grants limit what the server returns. A process with access to the owner's OS account, files, or keys still has that access; grants do not sandbox it. Hosted model providers can see the plaintext returned through their grants.

The HTTP server supports OAuth/DPoP, capture, and owner-approval APIs for separate clients. It has no bundled application or approval UI. Existing /mobile/... API names are preserved for compatibility; removed client pages and assets return 404.

Keep company and personal data separate

Initialize company and personal stores independently. Give each its own runtime identity and credentials, and select the store with an explicit --dir path. Directory names alone provide no OS isolation. Run untrusted company agents under a separate OS account or on a separate host.

Do not put API keys, recovery phrases, or private brain data in Git, skills, container layers, or machine images. Credential adapters retain secret values; HC stores opaque capability references and grants specific operations.

Documentation

• Mission and scope and scope evals.
• Operator skill: sync, workspaces, grants, secrets, remote storage, services, and recovery commands.
• Agent skill: scoped knowledge discovery.
• Architecture and format specification.
• Screenpipe backup adapter: legacy SQLite and hybrid SQLite + Parquet archives.
• Harness context plan: bounded evidence, capture provenance, skills, handoffs and independent adapters.
• Threat model and constraints.
• Failure cases and design decisions.
• Roadmap, contributing, and security reporting.

Development

cargo fmt --all -- --check
cargo clippy --locked --all-targets -- -D warnings
cargo test --locked
npm test
npm pack --dry-run
cargo package --locked

MIT licensed. See LICENSE.