A local document agent for accurate, cited answers from your files.

Quick Start

# Install UV (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install Heph
uv tool install heph@latest

# Create an armory for your files
heph armory init [name]

# Add materials that Heph can answer from
cp ~/Downloads/[file] ~/.armories/[name]/materials/

# Start Heph in that armory
heph [name]

Armory layout

An armory is a normal folder:

~/.armories/[name]/
├── materials/            # PDFs, Office docs, notes, code to cite
│   ├── [file].pdf
│   └── [file].md
├── .harness/             # Local Heph state
│   ├── armory.toml       # Armory marker
│   ├── rag_index.json    # Retrieval index
│   ├── memory.json       # Armory memory
│   ├── chats/            # Saved sessions
│   ├── traces/           # JSONL traces when enabled
│   ├── usage/            # Token and cost snapshots
│   └── ignore            # Indexing ignore rules
└── README.md             # Armory notes

materials/ holds files Heph can index and cite. .harness/ holds local state: the retrieval index, memory, chats, traces, usage snapshots, and ignore rules. Copy or sync the armory folder to move work between machines; configure provider credentials again on each machine.

Read Armories for storage, indexing, and memory details.

Installation

Note

Heph is currently in beta, so unexpected issues may occur. Please report them if they have not already been reported.

Using UV (recommended)

Install UV:

curl -LsSf https://astral.sh/uv/install.sh | sh

Then Heph:

uv tool install heph@latest

Using Pip

pip install heph

Updating

heph update

Check the installed version:

heph --version

Docs

Getting started
Armories
CLI reference
Configuration
Models
Trust and ownership
Privacy
Architecture
SDK
Troubleshooting
Developers
Runbooks

Contributing

See CONTRIBUTING.md for local development, tests, and pull request guidelines.

Safety

Analytics and crash reporting are opt-in from /settings. Source and Git installs do not enable hosted diagnostics by default.

Model-generated terminal commands are not exposed as a default agent tool. Explicit ! terminal escapes and armory plugins should only be used in armories you trust.