@holt-os/holt 0.3.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +55 -11
  2. package/dist/cli.js +1909 -221
  3. package/package.json +3 -3
  4. package/config.example.yml +0 -40
package/README.md CHANGED
@@ -6,7 +6,7 @@ Holt is an open-source, self-hosted personal agent OS. Clone it, pick your skill
6
6
 
7
7
  > A *holt* is a small wood: a sheltered place where things are kept and grow. That's the idea. A private home for your knowledge that compounds over time.
8
8
 
9
- > **Status: early but usable, and it remembers now.** `holt init`, `holt chat`, and persistent memory work today. A "brain" is an agent CLI (Claude Code, Codex, or Gemini). Holt can install a missing one for you and hand off to its sign-in, you can switch brains mid-conversation without losing context, and every session adds to a private memory in that folder that future sessions recall from. Skills and the knowledge graph view are the next phases.
9
+ > **Status: young but genuinely useful.** Working today: `holt init` and `holt chat`, brains as agent CLIs (Claude Code, Codex, Gemini) or direct API connections with your own key, mid-conversation brain switching that keeps context, persistent per-folder memory with semantic recall, skills in the portable SKILL.md format, and `holt graph`: your memory drawn as an interactive knowledge graph.
10
10
 
11
11
  ---
12
12
 
@@ -38,6 +38,7 @@ During `holt init` you:
38
38
  2. **Choose brains** (claude, codex, gemini). Holt installs any you pick that are missing.
39
39
  3. **Sign in.** For a newly installed brain, Holt starts that tool's own login (browser or its own prompt). Holt never stores your credentials.
40
40
  4. **Pick a default** brain and, optionally, a **launch command** (a short word like `ai` that runs `holt chat`).
41
+ 5. **Enable semantic memory.** If you say yes, Holt sets up a local [Ollama](https://ollama.com) with a small embed model so recall works by meaning, fully offline.
41
42
 
42
43
  ## Using it
43
44
 
@@ -46,8 +47,11 @@ Inside `holt chat`:
46
47
  ```
47
48
  /brain list your brains and see which is active
48
49
  /brain gemini switch brain. your conversation context is kept
50
+ /skill <name> run a skill on your input
49
51
  /memory memory stats. /memory <query> previews what recall would surface
50
- /setting configure brains and your launch command
52
+ /output show or set the save format: markdown | html
53
+ /save [name] save the last reply to a file in this folder
54
+ /setting configure brains, API brains, and your launch command
51
55
  /clear forget this session (saved memory stays)
52
56
  /help show commands
53
57
  /exit leave
@@ -61,7 +65,7 @@ Every exchange is saved to `<folder>/.holt/memory/turns.jsonl`, private and loca
61
65
 
62
66
  Two recall modes, picked automatically:
63
67
 
64
- - **Semantic** (best): if a local [Ollama](https://ollama.com) is running with an embedding model (`ollama pull nomic-embed-text`), recall matches by meaning. Asking "who owns my apartment" finds "my landlord is called Pieter". No API keys, nothing leaves your machine.
68
+ - **Semantic** (best): a local [Ollama](https://ollama.com) with an embedding model, which `holt init` offers to set up for you. Recall matches by meaning: asking "who owns my apartment" finds "my landlord is called Pieter". No API keys, nothing leaves your machine.
65
69
  - **Keyword** (fallback): with no Ollama, recall matches by word overlap. Still useful, zero setup.
66
70
 
67
71
  Inspect it any time:
@@ -69,9 +73,12 @@ Inspect it any time:
69
73
  ```bash
70
74
  holt memory # stats for this folder
71
75
  holt memory search <query> # find remembered moments
76
+ holt memory embed # embed older moments for semantic recall
72
77
  holt memory clear # wipe this folder's memory
73
78
  ```
74
79
 
80
+ Turns saved before semantic memory was enabled are upgraded in one pass with `holt memory embed`.
81
+
75
82
  Long conversations stay cheap: only recent turns are replayed verbatim, older context comes back through recall.
76
83
 
77
84
  ## Brains
@@ -84,15 +91,52 @@ A brain is an agent CLI installed and logged in on your machine. No API keys to
84
91
  | Codex | `codex` | `npm i -g @openai/codex` |
85
92
  | Gemini CLI | `gemini` | `npm i -g @google/gemini-cli` |
86
93
 
87
- `holt init` runs these for you when you pick a brain that is missing. You can also sign in any time with `holt login <brain>`. Raw API providers are planned for a later phase.
94
+ `holt init` runs these for you when you pick a brain that is missing. You can also sign in any time with `holt login <brain>`.
95
+
96
+ ### Direct API brains
97
+
98
+ A brain can also be a direct provider connection: no CLI install, your own key. Run `holt setting` and pick `[c] connect API brain`, or say yes to the API-brain question in `holt init`. Choose a provider (anthropic, openai, gemini), a model (suggestions offered, type anything), and a short name. For the key, paste a raw key (stored in `~/.holt/credentials.json`, mode 600) or give the name of an env var that holds it. Resolution order: the brain's `keyEnv`, the credentials file, then the standard env var (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`). API brains stream and share memory exactly like CLI brains; switch with `/brain <name>`.
99
+
100
+ ## See your memory: `holt graph`
101
+
102
+ `holt graph` turns this folder's memory into a picture you can walk. It writes one self-contained HTML file to `./.holt/graph.html` and opens it in your browser. No server, no CDN, no tracking: one file you can keep or share.
103
+
104
+ - Every turn is a node: yours glow amber, the assistant's cyan, and turns from the same session share a colored ring.
105
+ - Recurring ideas surface as concept nodes that tie related turns together.
106
+ - Turns that mean similar things (when local embeddings exist) get a strong link.
107
+ - Drag to pan, scroll to zoom, click a turn to read it in full, click a concept to light up its turns, and search to highlight matching memory live.
108
+
109
+ Options: `--out <path>` to write elsewhere, `--no-open` to skip the browser.
110
+
111
+ ## Skills
112
+
113
+ A skill is a folder with a `SKILL.md`: YAML frontmatter (`name`, `description`) plus Markdown instructions. Same convention as agentskills.io and Claude Code, so skills are portable both ways. Skills are prompt text only; Holt never executes their contents.
114
+
115
+ Holt looks in two places (workspace wins on a name clash): `./.holt/skills/` for this folder, `~/.holt/skills/` for every folder (`--global`).
116
+
117
+ ```
118
+ holt skill list list installed skills
119
+ holt skill show <name> print a skill
120
+ holt skill create <name> [--global] scaffold a new skill
121
+ holt skill add <src> [--global] install from a git URL or local path
122
+ holt skill remove <name> delete a skill
123
+ ```
124
+
125
+ In chat, run one with `/skill <name> [your input]`. Available skills are also listed to the brain each turn, so it knows what it can be asked to follow.
126
+
127
+ ## Output format
128
+
129
+ Replies print as markdown. `/output html` (or `markdown`) switches the save format and persists it. `/save [name]` writes the last reply to the current folder: `.md`, or a small self-contained dark-theme `.html` page.
88
130
 
89
131
  ## Commands
90
132
 
91
133
  ```
92
134
  holt init set up (trust, brains, sign-in, defaults) for this folder
93
135
  holt chat start a session that remembers past ones
94
- holt memory inspect memory: holt memory [search <query> | clear]
95
- holt setting configure brains and launch command
136
+ holt graph see your memory as an interactive knowledge graph
137
+ holt skill manage skills: list | show | create | add | remove
138
+ holt memory inspect memory: holt memory [search <query> | embed | clear]
139
+ holt setting configure brains, API brains, and launch command
96
140
  holt login <brain> sign in to claude, codex, or gemini
97
141
  holt version print version
98
142
  holt help show help
@@ -104,7 +148,7 @@ holt help show help
104
148
 
105
149
  ## Architecture
106
150
 
107
- Small strongly-typed **TypeScript core** (command dispatch, brain router, transcript, and a plugin dispatcher coming with skills). Brains and, soon, skills and channels are adapters. See [`ARCHITECTURE.md`](./ARCHITECTURE.md).
151
+ Small strongly-typed **TypeScript core**, zero runtime dependencies: command dispatch, brain adapters (CLI spawn and direct API streaming), transcript ownership, memory with recall, skills, and the graph renderer. See [`ARCHITECTURE.md`](./ARCHITECTURE.md) and [`CONFIGURATION.md`](./CONFIGURATION.md).
108
152
 
109
153
  ## Roadmap
110
154
 
@@ -112,11 +156,11 @@ Built in always-shippable phases toward a full-vision v1:
112
156
 
113
157
  0. **Skeleton and chat**: trust, init with install and sign-in, chat, brain switching with kept context *(shipped)*
114
158
  1. **Memory**: per-folder store, semantic recall via local embeddings with keyword fallback, streaming replies *(shipped)*
115
- 2. **Any LLM directly**: raw provider brains and an HTML or Markdown output toggle
116
- 3. **Skills**: install, search, and publish in the agentskills.io format
117
- 4. **Knowledge graph**: a view where you can see and navigate your own memory
159
+ 2. **Any LLM directly**: API brains with your own key, HTML or Markdown output *(shipped)*
160
+ 3. **Skills**: portable SKILL.md skills, create/add/run *(shipped)*
161
+ 4. **Knowledge graph**: see and navigate your own memory with `holt graph` *(shipped)*
118
162
  5. **Orchestration**: a local model works, a cloud model reviews the risky steps
119
- 6. **Channels and polish**: Telegram, docs, one-command setup
163
+ 6. **Channels and polish**: Telegram, docs site, skill registry publishing
120
164
 
121
165
  ## Contributing
122
166