Heph

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

Heph is built around normal folders. An armory keeps your documents in materials/ and Heph-owned local state in .harness/, so the armory stays portable and inspectable.

What Heph Does

• Answers from local armory materials with verifiable citations.
• Indexes PDFs, Office documents, notes, code, and other supported text sources.
• Opens retrieved evidence and source context from the terminal UI.
• Keeps chats, retrieval indexes, memory, traces, and usage snapshots in local armory state.
• Lets provider and model choices remain configurable instead of hardcoded.
• Exposes a Python SDK for native apps, GUI shells, and automation.

Install

uv tool install heph@latest

You can also install with pip:

pip install heph

Heph requires Python 3.13 or newer.

Update

heph update
heph --version

Quick Start

heph armory init my-notes
cp ~/Downloads/example.pdf ~/.armories/my-notes/materials/
heph my-notes

Inside Heph, ask questions about your materials. When Heph cites evidence, use the Evidence panel or /evidence command to inspect the cited source context.

Trust Model

Heph is local-first beta software. Materials remain in your armory, and memory is scoped to that armory unless you explicitly choose to move or share state. Analytics and crash reporting are opt-in from /settings.

Model providers may receive prompt content when selected for a turn. Review Trust and ownership and Privacy for the full data, cache, prompt, and compute contract.

Docs

• Getting started
• Armories
• CLI reference
• Configuration
• Models
• SDK
• Troubleshooting

Development

The public package bundles the Heph CLI, harness, AI runtime, interfaces, and extension contracts into one installable distribution. Repository development still keeps those layers separated under packages/.

uv run pytest --no-cov packages/heph/test
uv run heph --help
uv run python -m scripts.check_repo_policies
uv run lint-imports