Metadata-Version: 2.4
Name: hugr-cli
Version: 0.6.0
Summary: Meta-CLI and suite hub for the hugr memory suite (yaams, cognitive-ledger, owa-piggy, owa-tools)
Author: Carl Joakim Damsleth
License: MIT License
        
        Copyright (c) 2026 Carl Joakim Damsleth
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/damsleth/hugr
Project-URL: Source, https://github.com/damsleth/hugr
Keywords: hugr,memory,cli,agent
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Environment :: Console
Classifier: Development Status :: 4 - Beta
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1
Requires-Dist: PyYAML>=6
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Provides-Extra: tui
Requires-Dist: textual>=0.60; extra == "tui"
Requires-Dist: pytest-asyncio>=0.23; extra == "tui"
Provides-Extra: web
Requires-Dist: fastapi>=0.110; extra == "web"
Requires-Dist: uvicorn[standard]>=0.30; extra == "web"
Requires-Dist: jinja2>=3.1; extra == "web"
Provides-Extra: server
Requires-Dist: fastapi>=0.110; extra == "server"
Requires-Dist: uvicorn[standard]>=0.30; extra == "server"
Requires-Dist: jinja2>=3.1; extra == "server"
Provides-Extra: all
Requires-Dist: hugr-cli[server,tui,web]; extra == "all"
Dynamic: license-file

<p align="center">
  <img src="hugr.png" alt="hugr logo" style="max-height: 200px;" height="200">
</p>

# ᚼᚢᚴᛦ - (/ˈhuɡr/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
![status](https://img.shields.io/badge/status-pre--release-orange)

**A local-first memory suite for AI agents.** One install gets you a
two-tier memory store, an M365 read/write surface, and a single CLI
that ties them together. Your data stays on your machine.

`hugr` is the umbrella over four independent tools that already work
on their own. The umbrella adds one verb surface, one install
command, and one place to find what is in the box.

The name `hugr` is from Old Norse, where it means "mind, thought,
sense" - and in the Norse conception of self, specifically the part
of the mind that can travel outside the body to see and act on
distant things. The wordmark in Younger Futhark is ᚼᚢᚴᛦ:
hagall, úr, kaun, yr.

```
                            hugr (meta-CLI + suite hub)
                                       |
              +------------------------+------------------------+
              |               |                |                |
            YAAMS    cognitive-ledger    owa-piggy        owa-tools
         (Tier 1 raw) (Tier 2 curated)  (M365 auth)   (M365 read/write)
```

## What's in the box

| Tool | Purpose | Binaries |
| --- | --- | --- |
| [**YAAMS**](https://github.com/damsleth/yaams) | Tier 1 raw memory store - every iMessage, mail, calendar event, GitHub issue, ingested and queryable from a single SQLite file. | `yaams` |
| [**cognitive ledger**](https://github.com/damsleth/cognitive-ledger) | Tier 2 curated atomic notes engine - the gems you promote out of YAAMS and keep forever as markdown with frontmatter. | `ledger`, `ledger-obsidian`, `sheep` |
| [**owa piggy**](https://github.com/damsleth/owa-piggy) | Microsoft 365 auth broker - turns your existing Outlook Web session into a reusable token. No app registration. | `owa-piggy` |
| [**owa tools**](https://github.com/damsleth/owa-tools) | M365 read/write CLI suite - calendar, mail, Graph, OneDrive, scheduling, people lookup, all JSON-by-default. | `owa`, `owa-cal`, `owa-mail`, `owa-graph`, `owa-doctor`, `owa-people`, `owa-sched`, `owa-drive` |

`hugr` itself adds one more binary that routes the verbs above into
a single user-facing surface.

## Install

```bash
brew install damsleth/tap/hugr
hugr init --quick
hugr hello
```

Or via pipx (Python):

```bash
pipx install "hugr-cli[all]"   # CLI + TUI + web + server
hugr init --quick
```

Full install + setup story in [`docs/installation.md`](docs/installation.md).

## A taste of what it does

```bash
hugr recall "what did we decide at the brand kickoff?"
hugr find person nina
hugr inbox                                # unread mail + today + loops + promotions
hugr remember "Nina prefers early flights" --yes
hugr send mail --to a@example.com --subject "lunch" --body "12:00?" --yes
hugr book propose "Standup" --who vibeke@example.com --duration 30 --date tomorrow
hugr book commit  "Standup" --who vibeke@example.com --duration 30 --date tomorrow --slot 0 --yes
hugr tui                                  # Textual TUI
hugr web                                  # FastAPI web on 127.0.0.1:7777
hugr server                               # deploy-ready FastAPI runtime
hugr sync push --yes                      # encrypted state to a private GitHub repo
```

Every JSON-capable command accepts `--json` (machine mode) and
`--pretty` (human rendering). Exit codes follow
[CONVENTIONS.md](CONVENTIONS.md):
`0` ok, `1` user error, `2` transient, `3` auth, `4` not found,
`5` partial success.

## Documentation

Start with [`docs/`](docs/):

| Doc | What it covers |
| --- | --- |
| [`docs/installation.md`](docs/installation.md) | Install + first-time wizard |
| [`docs/quickstart.md`](docs/quickstart.md) | Five-minute tour of the verbs |
| [`docs/cli-reference.md`](docs/cli-reference.md) | Every command and flag, with examples |
| [`docs/recall.md`](docs/recall.md) | `recall`, `find`, `inbox` - the fused query verbs |
| [`docs/mutations.md`](docs/mutations.md) | `send`, `book`, `remember`, confirmation rules |
| [`docs/sessions.md`](docs/sessions.md) | Session model + working sets |
| [`docs/surfaces.md`](docs/surfaces.md) | TUI, web UI, `hugr server` |
| [`docs/sync.md`](docs/sync.md) | Cross-device state sync over git + age |
| [`docs/config.md`](docs/config.md) | Master config + env vars |
| [`docs/troubleshooting.md`](docs/troubleshooting.md) | Common errors and fixes |

Architecture and contract:

- [`SUITE.md`](SUITE.md) - data flow and architecture diagram.
- [`CONVENTIONS.md`](CONVENTIONS.md) - the CLI contract every tool in
  the suite conforms to.
- [`deploy/docs/deploy.md`](deploy/docs/deploy.md) - Docker / systemd /
  Cloudflare / tailscale recipes for `hugr server`.

## Skills

Two agent skill repos sit on top of `hugr`:

- [`damsleth/SKILLS`](https://github.com/damsleth/SKILLS) - public,
  reusable agent skills. Includes `/memory`, which routes through
  `hugr`.
- `damsleth/SKILLS-private` - personal-infra `cj-*` skills (timereg,
  did, weekly review). Same installer pattern; private repo.

Skills wrap `hugr`. `hugr` does not call skills. One direction, no
circular dependencies.

## License

MIT. See [LICENSE](LICENSE).
