<!-- screenpipe — AI that knows everything you've seen, said, or heard -->

# 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](docs/CONSTRAINTS.md) 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:

```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, grants, and configured peers. 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 <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:

```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", "<grant-id>", "--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 <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](MISSION.md) and [scope evals](evals/scope/README.md).
- [Operator skill](skills/hyperconsciousness-ops/SKILL.md): sync, workspaces, grants, secrets,
  remote storage, services, and recovery commands.
- [Agent skill](skills/hyperconsciousness/SKILL.md): scoped knowledge discovery.
- [Architecture](docs/ARCHITECTURE.md) and [format specification](docs/SPEC.md).
- [Screenpipe backup adapter](docs/SCREENPIPE-ADAPTER.md): legacy SQLite and hybrid SQLite + Parquet archives.
- [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).
- [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).