# Hyperconsciousness (`hc`) HC is an encrypted, append-only knowledge store for humans and agents. One trusted node owns the store; other devices use its authenticated API. You choose what an agent can access and for how long through scoped, expiring grants. The node can run on your own machine or server. 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](docs/CONSTRAINTS.md) before using it for important data. The package is `hyperconsciousness`; run it with `hc`. Read [HC for humans](HUMANS.md) for permissions, sharing, privacy and working with agents. Agents can follow the [usage skill](skills/hyperconsciousness/SKILL.md). ## Install On macOS or Linux, install the latest published alpha with one command: ```sh 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](https://github.com/louis030195/hyperconsciousness/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](docs/RELEASING.md#automatic-cli-updates). To connect to an existing organization, use its connection pack: ```sh 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](docs/HOSTED-ACCESS.md) for other clients and access boundaries. The company connection is separate from your personal brain. ## Ingest chats and tools The [ingestion skill catalog](skills/README.md) 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: ```sh 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](dashboard/README.md) to inspect storage, file metadata, identity, and grants. You can navigate with the keyboard or use its command menu. The [UI guide and screenshots](dashboard/docs/ui/README.md) 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](AGENTS.md#optional-local-dashboard) explain how. Check the [prerequisites](dashboard/README.md#run-locally), then run these commands from the repository root: ```sh cd dashboard bun install --frozen-lockfile bun run build bun run start ``` Open , 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: ```sh sudo apt-get install build-essential pkg-config libssl-dev libdbus-1-dev ``` Build the source on macOS or Linux: ```sh 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](docs/RELEASING.md). ## 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: ```sh 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`: ```sh 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: ```json { "mcpServers": { "hc": { "command": "/absolute/path/to/hc", "args": ["mcp", "--as", "", "--dir", "/absolute/path/to/hc-demo"] } } } ``` MCP search supports an opt-in [lexical relevance mode](docs/RANKED_RECALL.md) 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](docs/COMPANY-ACCESS.md). Company mode checks current membership on every tool call and requires client-side request signing. ```sh hc revoke --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. Small devices can [query a trusted HC node](docs/QUERY-NODES.md) through the same MCP tools and `hc find` interface without replicating the brain. An opt-in default reader preserves explicit local connections. 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](MISSION.md) and [scope evals](evals/scope/README.md). - [Operator skill](skills/hyperconsciousness-ops/SKILL.md): workspaces, grants, secrets, object-storage backup, and recovery commands. - [Agent skill](skills/hyperconsciousness/SKILL.md): scoped knowledge discovery. - [Architecture](docs/ARCHITECTURE.md) and [format specification](docs/SPEC.md). - [Central-only migration](docs/CENTRAL-ONLY-MIGRATION.md): move an existing store to one trusted node. - [Harness context plan](docs/HARNESS-CONTEXT-PLAN.md): bounded evidence, capture provenance, skills, handoffs and independent adapters. - [Threat model and constraints](docs/CONSTRAINTS.md). - [Failure cases](docs/EDGE-CASES.md) and [design decisions](docs/DECISIONS.md). - [Historical roadmap](docs/ROADMAP.md), [contributing](CONTRIBUTING.md), and [security reporting](SECURITY.md). ## Development ```sh 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](LICENSE).