hippo-memory 3.7.1 → 3.8.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.
- package/README.md +27 -26
- package/dist/base/util/env.d.ts +1 -0
- package/dist/base/util/env.js +2 -0
- package/dist/base/util/version.d.ts +1 -1
- package/dist/base/util/version.js +1 -1
- package/dist/surface/cli/embedder-install.d.ts +18 -0
- package/dist/surface/cli/embedder-install.js +121 -0
- package/dist/surface/cli/init.js +32 -1
- package/dist/surface/cli/maintenance.js +2 -2
- package/dist/surface/cli/verbs/memory.js +3 -1
- package/extensions/openclaw-plugin/openclaw.plugin.json +1 -1
- package/extensions/openclaw-plugin/package.json +1 -1
- package/openclaw.plugin.json +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -18,7 +18,7 @@ Inspired by the human hippocampus, hippo saves what you teach one coding agent i
|
|
|
18
18
|
Works with: Claude Code, Codex, Cursor, Pi, OpenClaw, OpenCode, any MCP client
|
|
19
19
|
Imports from: ChatGPT, Claude (CLAUDE.md), Cursor (.cursorrules), Slack, markdown
|
|
20
20
|
Storage: SQLite with markdown mirrors you can read and commit
|
|
21
|
-
Dependencies: Zero runtime deps. Node.js 22.16+.
|
|
21
|
+
Dependencies: Zero runtime deps. Node.js 22.16+. Embeddings: `hippo init` installs the local Transformers.js embedder (`@huggingface/transformers@4.3.2`, about 480 MB) into a global npm install, and `--no-embeddings` skips it. An API embedder (OpenAI/Voyage/Cohere) is opt-in.
|
|
22
22
|
```
|
|
23
23
|
|
|
24
24
|
**Contents:** [Install](#install) · [Follow one memory](#follow-one-memory) · [What hippo does](#what-hippo-does) · [Results](#repeat-mistakes-per-100-chances) · [Setup in detail](#setup-in-detail) · [Agent setup](#framework-integrations) · [MCP server](#mcp-server) · [How it works](#how-it-works) · [CLI](#cli-reference) · [Comparison](#comparison) · [Benchmarks](#benchmarks) · [FAQ](#faq) · [Contributing](#contributing)
|
|
@@ -44,7 +44,7 @@ hippo init
|
|
|
44
44
|
|
|
45
45
|
Installing the package alone captures nothing, and what runs after init depends on the agent.
|
|
46
46
|
|
|
47
|
-
`hippo init` creates a `.hippo/` store in the project, adds a short block to an existing `CLAUDE.md` or `AGENTS.md`, installs Claude Code's hooks
|
|
47
|
+
`hippo init` creates a `.hippo/` store in the project, adds a short block to an existing `CLAUDE.md` or `AGENTS.md`, installs Claude Code's hooks, schedules a daily run at 6:15am that stores lessons from the day's commits and installs the local embedder for recall by meaning. `--no-hooks`, `--no-schedule` and `--no-embeddings` skip those parts. Codex runs hippo's hooks only once you trust them in `/hooks`. `hippo doctor` checks the install. [What hippo init changes](#what-hippo-init-changes) lists every file it writes, and [llms-install.md](llms-install.md) is the guide the prompt above follows.
|
|
48
48
|
|
|
49
49
|
---
|
|
50
50
|
|
|
@@ -195,6 +195,7 @@ Run `hippo init` inside one project. This is everything it writes, in the projec
|
|
|
195
195
|
- **OpenCode,** when the project has `.opencode/` or `opencode.json`: a plugin at `~/.config/opencode/plugins/hippo.ts`.
|
|
196
196
|
- **Codex,** when the project has `AGENTS.md` or `.codex` and Codex is installed (`$CODEX_HOME`, else `~/.codex`, exists): 2 hook entries in Codex's `hooks.json`, one on UserPromptSubmit that sends your pinned memories plus up to 5 that match the prompt with every prompt and one on SessionStart after a compaction. **Codex runs them only after you trust them once in `/hooks`.** Init also prints `hippo hook install codex`, the opt-in that wraps the Codex launcher to capture sessions; `hippo hook uninstall codex` removes hippo's hooks and the wrapper.
|
|
197
197
|
- **A daily run at 6:15am,** one per machine: a crontab line on Linux and macOS, a scheduled task named `hippo-daily-runner` on Windows. It runs `hippo learn --git --days 1` and then `hippo sleep` in every project listed in `~/.hippo/workspaces.json`, and init adds this project to that list.
|
|
198
|
+
- **The local embedder,** when hippo is a global npm install and no embedder is installed yet: `@huggingface/transformers@4.3.2` in the same global folder, about 480 MB. It goes in before anything else, can take a few minutes, and runs with `--ignore-scripts`, so no install script in that package tree runs. Its model (`Xenova/all-MiniLM-L6-v2`, 87 MB) downloads from Hugging Face the first time hippo embeds. Under npx, pnpm, yarn, bun or as a project dependency, init prints the command for that setup instead. `npm uninstall -g hippo-memory` leaves the embedder in place; `npm uninstall -g @huggingface/transformers` removes it.
|
|
198
199
|
- **Agent memories.** On every run, the notes your coding agents keep about this project go into its store, and the ones about you go into the global store. [Agent memories](#agent-memories) lists what is read.
|
|
199
200
|
|
|
200
201
|
```bash
|
|
@@ -210,7 +211,7 @@ hippo init
|
|
|
210
211
|
# Scheduled machine-level daily runner (6:15am) via crontab
|
|
211
212
|
```
|
|
212
213
|
|
|
213
|
-
To leave parts out: `--no-hooks` skips the instruction files and hooks, `--no-schedule` the daily run, and `--no-learn` the git history and agent memory import. `HIPPO_SKIP_AUTO_INTEGRATIONS=1` skips the same files and hooks that `--no-hooks` does,
|
|
214
|
+
To leave parts out: `--no-hooks` skips the instruction files and hooks, `--no-schedule` the daily run, `--no-embeddings` the embedder install, and `--no-learn` the git history and agent memory import. `HIPPO_SKIP_AUTO_INTEGRATIONS=1` skips the same files and hooks that `--no-hooks` does, `HIPPO_SKIP_SCHEDULE=1` skips the daily run as `--no-schedule` does, and `HIPPO_SKIP_EMBEDDER_INSTALL=1` skips the embedder as `--no-embeddings` does.
|
|
214
215
|
|
|
215
216
|
### Agent memories
|
|
216
217
|
|
|
@@ -1030,27 +1031,27 @@ Full integration details: [integrations/](integrations/)
|
|
|
1030
1031
|
|
|
1031
1032
|
Hippo is for coding agents on machines you control. [Mem0](https://hippo-memory.com/vs/mem0/) fits better when the memory belongs to your app's end users, [Zep](https://hippo-memory.com/vs/zep/) when you want a managed knowledge graph built from business data, and [Letta Code](https://hippo-memory.com/vs/letta/) when you want an agent that edits its own memory. The table is a feature snapshot, not a verdict, and it holds no scores: [Benchmarks](#benchmarks) has those, split by setup.
|
|
1032
1033
|
|
|
1033
|
-
| Feature\* | Hippo | [MemPalace](https://github.com/milla-jovovich/mempalace) | [Mem0](https://github.com/mem0ai/mem0) | [Basic Memory](https://github.com/basicmachines-co/basic-memory) | [
|
|
1034
|
-
|
|
1035
|
-
| Decay by default | Yes | No | No | No | No | No | No | No | No |
|
|
1036
|
-
| Retrieval strengthening | Yes | No | No | No | No | No |
|
|
1037
|
-
| Reward-proportional decay | Yes | No | No | No | No | No | No | No | No |
|
|
1038
|
-
| Hybrid search (BM25 + embeddings) | Yes | Embeddings + spatial | Yes (semantic + BM25 + entity) | No | Yes (
|
|
1039
|
-
| Schema acceleration / knowledge graph | Yes (schema) | No | Partial (entity linking; graph memory on Pro) | No | Yes (
|
|
1040
|
-
| Conflict detection + resolution | Yes | No | Partial (hosted platform marks superseded facts) | No | Yes (
|
|
1041
|
-
| Multi-agent shared memory | Yes | No | No | No | Yes
|
|
1042
|
-
| Transfer scoring | Yes | No | No | No | No | No | No | No | No |
|
|
1043
|
-
| Outcome tracking | Yes | No | No | No | No | No | No | No |
|
|
1044
|
-
| Confidence tiers | Yes | No | No | No | No
|
|
1045
|
-
| Spatial organization | No | Yes (wings/halls/rooms) | No | No | No | No | No | No | No |
|
|
1046
|
-
| Lossless compression | No | Yes (AAAK, 30x) | No | No | No | No | No | No | No |
|
|
1047
|
-
| Cross-tool import (ChatGPT/Claude/Cursor) | Yes | No | No | No |
|
|
1048
|
-
| Auto-hook install | Yes | No | No | No | No | No | No | No | No |
|
|
1049
|
-
| MCP server | Yes | Yes | Yes (hosted, needs an account) | Yes | Yes (
|
|
1050
|
-
| Zero runtime deps | Yes | No (ChromaDB) | No | No | No (
|
|
1051
|
-
| Git-friendly | Yes | No | No | Yes |
|
|
1052
|
-
| Framework agnostic | Yes | Yes | Partial | Yes | Yes | Yes | Yes | Yes | Yes |
|
|
1053
|
-
| License | MIT | (open) | Apache-2.0 | (open) |
|
|
1034
|
+
| Feature\* | Hippo | [MemPalace](https://github.com/milla-jovovich/mempalace) | [Mem0](https://github.com/mem0ai/mem0) | [Basic Memory](https://github.com/basicmachines-co/basic-memory) | [Zep](https://www.getzep.com/) | [Letta](https://github.com/letta-ai/letta-code) | [Cognee](https://www.cognee.ai/) | [Memoria](https://github.com/matrixorigin/Memoria) | [EverMind](https://evermind.ai/) |
|
|
1035
|
+
|---------|-------|-----------|------|-------------|-----|-------|--------|---------|----------|
|
|
1036
|
+
| Decay by default | Yes | No | No | No | No | No | No | No | No |
|
|
1037
|
+
| Retrieval strengthening | Yes | No | No | No | No | No | Partial (recall tuning) | No | Partial (Skill Memory distills patterns) |
|
|
1038
|
+
| Reward-proportional decay | Yes | No | No | No | No | No | No | No | No |
|
|
1039
|
+
| Hybrid search (BM25 + embeddings) | Yes | Embeddings + spatial | Yes (semantic + BM25 + entity) | No | Yes (graph + vec) | ? | Yes (GraphRAG) | Yes (vector + full-text) | Yes (mRAG, multi-modal) |
|
|
1040
|
+
| Schema acceleration / knowledge graph | Yes (schema) | No | Partial (entity linking; graph memory on Pro) | No | Yes (temporal KG) | No | Yes (auto-ontologies) | No (typed claims) | Yes (hierarchical: user/group/agent) |
|
|
1041
|
+
| Conflict detection + resolution | Yes | No | Partial (hosted platform marks superseded facts) | No | Yes (auto-invalidate stale facts) | No | No | Yes (auto-detect + quarantine) | Partial (temporal tracking) |
|
|
1042
|
+
| Multi-agent shared memory | Yes | No | No | No | Yes | Yes (shared memory blocks) | Yes | Yes (branch/merge across sessions) | Yes (multi-agent coordination) |
|
|
1043
|
+
| Transfer scoring | Yes | No | No | No | No | No | No | No | No |
|
|
1044
|
+
| Outcome tracking | Yes | No | No | No | No | No | No | No | Partial (Cases: agent trajectories) |
|
|
1045
|
+
| Confidence tiers | Yes | No | No | No | No | No | No | No | No |
|
|
1046
|
+
| Spatial organization | No | Yes (wings/halls/rooms) | No | No | No | No | No | No | No |
|
|
1047
|
+
| Lossless compression | No | Yes (AAAK, 30x) | No | No | No | No | No | No | No |
|
|
1048
|
+
| Cross-tool import (ChatGPT/Claude/Cursor) | Yes | No | No | No | ? | No | Partial (28 data sources) | No (Git ops) | Partial (mRAG: PDFs/images/URLs) |
|
|
1049
|
+
| Auto-hook install | Yes | No | No | No | No | No | No | No | No |
|
|
1050
|
+
| MCP server | Yes | Yes | Yes (hosted, needs an account) | Yes | Yes (hosted, needs an account) | Yes (hosted, needs an API key) | Yes (first-party Claude/LangGraph) | Yes | ? |
|
|
1051
|
+
| Zero runtime deps | Yes | No (ChromaDB) | No | No | No (managed service) | No (npm deps) | No (Python deps) | Yes (single Rust binary) | No (managed + OSS) |
|
|
1052
|
+
| Git-friendly | Yes | No | No | Yes | No | Yes (memory tracked in git) | No | Yes (Git is the model) | ? |
|
|
1053
|
+
| Framework agnostic | Yes | Yes | Partial | Yes | Yes | Yes | Yes | Yes | Yes |
|
|
1054
|
+
| License | MIT | (open) | Apache-2.0 | (open) | Proprietary cloud (Graphiti: Apache-2.0) | Apache-2.0 | MIT (core) | Apache-2.0 | Apache-2.0 (OSS) + cloud |
|
|
1054
1055
|
|
|
1055
1056
|
\* The Mem0, Zep and Letta columns were last checked against each vendor's own pages on 2026-09-28.
|
|
1056
1057
|
|
|
@@ -1152,7 +1153,7 @@ Every other benchmark we ran. Our setup differs from the published rows, so thes
|
|
|
1152
1153
|
|
|
1153
1154
|
### Finding the right session
|
|
1154
1155
|
|
|
1155
|
-
On LongMemEval-S, hippo's benchmark scripts put an answer session in the top five for 98.0% of 500 questions with the free local MiniLM embedder. That is the best of five settings, chosen after the run, on a measure close to its ceiling. Requiring every answer session, the same runs score 86.8 to 88.5
|
|
1156
|
+
On LongMemEval-S, hippo's benchmark scripts put an answer session in the top five for 98.0% of 500 questions with the free local MiniLM embedder. That is the best of five settings, chosen after the run, on a measure close to its ceiling. Requiring every answer session, the same runs score 86.8 to 88.5%. The `hippo recall` command on a default install scores 85.6% [82.4, 88.6]. On one store of all 19,195 sessions, recall fell to 47.2% in June 2026.
|
|
1156
1157
|
|
|
1157
1158
|
### What the two rerankers bought
|
|
1158
1159
|
|
|
@@ -1241,7 +1242,7 @@ On repeat mistakes, yes, in [one test of our own](https://github.com/kitfunso/hi
|
|
|
1241
1242
|
Issues and PRs welcome. Before contributing, run `hippo status` in the repo root to see the project's own memory.
|
|
1242
1243
|
|
|
1243
1244
|
The interesting problems:
|
|
1244
|
-
- **Recall as one store grows.** On LongMemEval-S, `hippo recall` on a default install scores 85.6% [82.4, 88.6] ([result](docs/evals/2026-09-28-recall-cli-longmemeval-result.md)), and on one store of all 19,195 sessions recall fell to 47.2% in June 2026. Requiring every answer session in the top five, the benchmark scripts score 86.8 to 88.5
|
|
1245
|
+
- **Recall as one store grows.** On LongMemEval-S, `hippo recall` on a default install scores 85.6% [82.4, 88.6] ([result](docs/evals/2026-09-28-recall-cli-longmemeval-result.md)), and on one store of all 19,195 sessions recall fell to 47.2% in June 2026. Requiring every answer session in the top five, the benchmark scripts score 86.8 to 88.5%. The lifecycle stress eval (ROADMAP Part III) is the next measurement.
|
|
1245
1246
|
- Better consolidation heuristics (LLM-powered merge vs current text overlap)
|
|
1246
1247
|
- Web UI / dashboard for visualizing decay curves and memory health
|
|
1247
1248
|
- Optimal decay parameter tuning from real usage data
|
package/dist/base/util/env.d.ts
CHANGED
|
@@ -45,6 +45,7 @@ export declare function envActiveScope(): string | null;
|
|
|
45
45
|
export declare function envTenant(): string;
|
|
46
46
|
export declare const envSkipAutoIntegrations: () => boolean;
|
|
47
47
|
export declare const envSkipSchedule: () => boolean;
|
|
48
|
+
export declare const envSkipEmbedderInstall: () => boolean;
|
|
48
49
|
export declare const envMcpStdio: () => boolean;
|
|
49
50
|
export declare const envRequireServer: () => boolean;
|
|
50
51
|
export declare const envReadOnly: () => boolean;
|
package/dist/base/util/env.js
CHANGED
|
@@ -16,6 +16,7 @@ const FLAGS = {
|
|
|
16
16
|
HIPPO_AVAILABILITY: false,
|
|
17
17
|
HIPPO_SKIP_AUTO_INTEGRATIONS: false,
|
|
18
18
|
HIPPO_SKIP_SCHEDULE: false,
|
|
19
|
+
HIPPO_SKIP_EMBEDDER_INSTALL: false,
|
|
19
20
|
HIPPO_MCP_STDIO: false,
|
|
20
21
|
HIPPO_REQUIRE_SERVER: false,
|
|
21
22
|
HIPPO_REQUIRE_SESSION_SCOPED_FRESH_TAIL: false,
|
|
@@ -200,6 +201,7 @@ export function envTenant() {
|
|
|
200
201
|
// Install and CLI switches.
|
|
201
202
|
export const envSkipAutoIntegrations = bool('HIPPO_SKIP_AUTO_INTEGRATIONS');
|
|
202
203
|
export const envSkipSchedule = bool('HIPPO_SKIP_SCHEDULE');
|
|
204
|
+
export const envSkipEmbedderInstall = bool('HIPPO_SKIP_EMBEDDER_INSTALL');
|
|
203
205
|
export const envMcpStdio = bool('HIPPO_MCP_STDIO');
|
|
204
206
|
export const envRequireServer = bool('HIPPO_REQUIRE_SERVER');
|
|
205
207
|
export const envReadOnly = bool('HIPPO_READ_ONLY');
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
* Single source of truth for the package version, written by scripts/sync-version.mjs; never
|
|
3
3
|
* edit by hand. Read by the db rollback guard, /health, MCP. A constant, not a runtime
|
|
4
4
|
* package.json read: the published bundle may lack package.json on a path ESM can resolve. */
|
|
5
|
-
export declare const PACKAGE_VERSION = "3.
|
|
5
|
+
export declare const PACKAGE_VERSION = "3.8.0";
|
|
6
6
|
/** The floor a store takes on its first expiring key: the first release with schema v53, set by
|
|
7
7
|
* hand in that release; scripts/checks/check-expiring-keys-floor.mjs gates it. */
|
|
8
8
|
export declare const EXPIRING_KEYS_MIN_BINARY = "1.64.0";
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
* Single source of truth for the package version, written by scripts/sync-version.mjs; never
|
|
3
3
|
* edit by hand. Read by the db rollback guard, /health, MCP. A constant, not a runtime
|
|
4
4
|
* package.json read: the published bundle may lack package.json on a path ESM can resolve. */
|
|
5
|
-
export const PACKAGE_VERSION = '3.
|
|
5
|
+
export const PACKAGE_VERSION = '3.8.0';
|
|
6
6
|
/** The floor a store takes on its first expiring key: the first release with schema v53, set by
|
|
7
7
|
* hand in that release; scripts/checks/check-expiring-keys-floor.mjs gates it. */
|
|
8
8
|
export const EXPIRING_KEYS_MIN_BINARY = '1.64.0';
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
import { type ExecFileSyncOptions } from 'node:child_process';
|
|
2
|
+
import type { EmbeddingsConfig } from '../../base/config/config.js';
|
|
3
|
+
export type RunNode = (file: string, args: readonly string[], opts: ExecFileSyncOptions) => void;
|
|
4
|
+
/** What the step reads from the machine; tests pass stand-ins. */
|
|
5
|
+
export interface EmbedderInstallDeps {
|
|
6
|
+
readonly run: RunNode;
|
|
7
|
+
readonly installed: () => boolean;
|
|
8
|
+
readonly exists: (file: string) => boolean;
|
|
9
|
+
readonly packageRoot: string;
|
|
10
|
+
readonly platform: NodeJS.Platform;
|
|
11
|
+
readonly nodePath: string;
|
|
12
|
+
}
|
|
13
|
+
/** How to install the local embedder where this hippo resolves it, as the end of a sentence. */
|
|
14
|
+
export declare function embedderInstallAdvice(deps?: EmbedderInstallDeps): string;
|
|
15
|
+
/** Installs the local embedder into hippo's own npm global folder, else prints how; never throws.
|
|
16
|
+
* --ignore-scripts: the tree ships prebuilt binaries, so no transitive install script runs. */
|
|
17
|
+
export declare function installLocalEmbedder(embeddings: EmbeddingsConfig, deps?: EmbedderInstallDeps): boolean;
|
|
18
|
+
//# sourceMappingURL=embedder-install.d.ts.map
|
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
// The init step that installs the local embedder beside a global hippo, so a default install
|
|
2
|
+
// recalls by meaning as well as by keyword while the package itself keeps no runtime dependencies.
|
|
3
|
+
import * as fs from 'node:fs';
|
|
4
|
+
import * as path from 'node:path';
|
|
5
|
+
import { execFileSync } from 'node:child_process';
|
|
6
|
+
import { PACKAGE_ROOT } from '../../base/config/package-root.js';
|
|
7
|
+
import { isEmbeddingAvailable } from '../../base/embeddings/local.js';
|
|
8
|
+
import { envSkipEmbedderInstall } from '../../base/util/env.js';
|
|
9
|
+
import { errorCode, errorFields, errorMessage, log } from '../../base/util/log.js';
|
|
10
|
+
/** Exact: a global install has no lockfile, so this pin is the one review gate on the tree. */
|
|
11
|
+
const EMBEDDER_PACKAGE = '@huggingface/transformers@4.3.2';
|
|
12
|
+
const INSTALL_TIMEOUT_MS = 10 * 60_000;
|
|
13
|
+
const NPM_CLI = path.join('node_modules', 'npm', 'bin', 'npm-cli.js');
|
|
14
|
+
const PROJECT_ADD = [
|
|
15
|
+
['pnpm-lock.yaml', 'pnpm add'],
|
|
16
|
+
['yarn.lock', 'yarn add --ignore-scripts'],
|
|
17
|
+
['bun.lock', 'bun add'],
|
|
18
|
+
['bun.lockb', 'bun add'],
|
|
19
|
+
];
|
|
20
|
+
const MACHINE = {
|
|
21
|
+
run: execFileSync,
|
|
22
|
+
installed: isEmbeddingAvailable,
|
|
23
|
+
exists: fs.existsSync,
|
|
24
|
+
packageRoot: PACKAGE_ROOT,
|
|
25
|
+
platform: process.platform,
|
|
26
|
+
nodePath: process.execPath,
|
|
27
|
+
};
|
|
28
|
+
/** npm puts globals in `{prefix}/node_modules` on Windows and `{prefix}/lib/node_modules`
|
|
29
|
+
* elsewhere, with no package.json above; pnpm, yarn, bun and npm projects are all projects. */
|
|
30
|
+
function layoutOf(deps) {
|
|
31
|
+
const parts = deps.packageRoot.split(/[\\/]/);
|
|
32
|
+
if (parts.includes('_npx'))
|
|
33
|
+
return { kind: 'npx' };
|
|
34
|
+
const first = parts.indexOf('node_modules');
|
|
35
|
+
if (first < 0)
|
|
36
|
+
return { kind: 'project', dir: deps.packageRoot };
|
|
37
|
+
const dir = parts.slice(0, first).join(path.sep) || path.sep;
|
|
38
|
+
const direct = first === parts.length - 2;
|
|
39
|
+
if (direct && !deps.exists(path.join(dir, 'package.json'))) {
|
|
40
|
+
if (deps.platform === 'win32')
|
|
41
|
+
return { kind: 'npm-global', prefix: dir };
|
|
42
|
+
if (path.basename(dir) === 'lib')
|
|
43
|
+
return { kind: 'npm-global', prefix: path.dirname(dir) };
|
|
44
|
+
}
|
|
45
|
+
return { kind: 'project', dir };
|
|
46
|
+
}
|
|
47
|
+
function adviceFor(layout, deps) {
|
|
48
|
+
if (layout.kind === 'npm-global') {
|
|
49
|
+
return `run: npm install -g --ignore-scripts ${EMBEDDER_PACKAGE}`;
|
|
50
|
+
}
|
|
51
|
+
if (layout.kind === 'npx') {
|
|
52
|
+
return 'install hippo globally (npm install -g hippo-memory), then run hippo init again';
|
|
53
|
+
}
|
|
54
|
+
const add = PROJECT_ADD.find(([lockfile]) => deps.exists(path.join(layout.dir, lockfile)))?.[1] ??
|
|
55
|
+
'npm install --ignore-scripts';
|
|
56
|
+
return `run \`${add} ${EMBEDDER_PACKAGE}\` in ${layout.dir}`;
|
|
57
|
+
}
|
|
58
|
+
/** How to install the local embedder where this hippo resolves it, as the end of a sentence. */
|
|
59
|
+
export function embedderInstallAdvice(deps = MACHINE) {
|
|
60
|
+
return adviceFor(layoutOf(deps), deps);
|
|
61
|
+
}
|
|
62
|
+
/** The npm that owns hippo's global folder, else the one shipped beside this node. */
|
|
63
|
+
function npmCliFor(prefix, deps) {
|
|
64
|
+
const lib = deps.platform === 'win32' ? '' : 'lib';
|
|
65
|
+
const nodeHome = path.dirname(deps.nodePath);
|
|
66
|
+
const beside = deps.platform === 'win32' ? nodeHome : path.join(path.dirname(nodeHome), 'lib');
|
|
67
|
+
return [path.join(prefix, lib, NPM_CLI), path.join(beside, NPM_CLI)].find(deps.exists);
|
|
68
|
+
}
|
|
69
|
+
/** execFileSync puts npm's exit code on the error it throws; a kill or a failed start leaves none. */
|
|
70
|
+
function failureLine(error) {
|
|
71
|
+
if (errorCode(error) === 'ETIMEDOUT')
|
|
72
|
+
return 'npm ran for 10 minutes, so hippo stopped it.';
|
|
73
|
+
if ('status' in error && Number.isInteger(error.status)) {
|
|
74
|
+
return `npm stopped with exit code ${String(error.status)}; its error is above.`;
|
|
75
|
+
}
|
|
76
|
+
return `npm did not start (${error.message.split(/\r?\n/, 1)[0]}).`;
|
|
77
|
+
}
|
|
78
|
+
/** Installs the local embedder into hippo's own npm global folder, else prints how; never throws.
|
|
79
|
+
* --ignore-scripts: the tree ships prebuilt binaries, so no transitive install script runs. */
|
|
80
|
+
export function installLocalEmbedder(embeddings, deps = MACHINE) {
|
|
81
|
+
if (embeddings.enabled === false || (embeddings.provider ?? 'local') !== 'local')
|
|
82
|
+
return false;
|
|
83
|
+
if (deps.installed())
|
|
84
|
+
return false;
|
|
85
|
+
if (envSkipEmbedderInstall()) {
|
|
86
|
+
console.log('HIPPO_SKIP_EMBEDDER_INSTALL=1, so init did not install local embeddings.');
|
|
87
|
+
return false;
|
|
88
|
+
}
|
|
89
|
+
const layout = layoutOf(deps);
|
|
90
|
+
const npmCli = layout.kind === 'npm-global' ? npmCliFor(layout.prefix, deps) : undefined;
|
|
91
|
+
if (layout.kind !== 'npm-global' || !npmCli) {
|
|
92
|
+
console.log(`Embeddings are off. For recall by meaning, ${adviceFor(layout, deps)}`);
|
|
93
|
+
return false;
|
|
94
|
+
}
|
|
95
|
+
console.log(`Installing local embeddings (${EMBEDDER_PACKAGE}, about 480 MB, and an 87 MB model on ` +
|
|
96
|
+
'first use) for recall by meaning. This can take a few minutes; --no-embeddings skips it.');
|
|
97
|
+
try {
|
|
98
|
+
deps.run(deps.nodePath, [
|
|
99
|
+
npmCli,
|
|
100
|
+
'install',
|
|
101
|
+
'--global',
|
|
102
|
+
'--prefix',
|
|
103
|
+
layout.prefix,
|
|
104
|
+
'--ignore-scripts',
|
|
105
|
+
EMBEDDER_PACKAGE,
|
|
106
|
+
], { stdio: ['ignore', 'inherit', 'inherit'], timeout: INSTALL_TIMEOUT_MS });
|
|
107
|
+
}
|
|
108
|
+
catch (err) {
|
|
109
|
+
const error = err instanceof Error ? err : new Error(errorMessage(err));
|
|
110
|
+
log.info(`embedder install failed: ${error.message}`, errorFields(error));
|
|
111
|
+
console.log(`${failureLine(error)} For recall by meaning, ${adviceFor(layout, deps)}`);
|
|
112
|
+
return false;
|
|
113
|
+
}
|
|
114
|
+
if (!deps.installed()) {
|
|
115
|
+
console.log(`npm finished, but hippo cannot find the package. For recall by meaning, ${adviceFor(layout, deps)}`);
|
|
116
|
+
return false;
|
|
117
|
+
}
|
|
118
|
+
console.log('Local embeddings are on.');
|
|
119
|
+
return true;
|
|
120
|
+
}
|
|
121
|
+
//# sourceMappingURL=embedder-install.js.map
|
package/dist/surface/cli/init.js
CHANGED
|
@@ -12,7 +12,7 @@ import { installOpencodePlugin } from '../hooks-install/opencode.js';
|
|
|
12
12
|
import { initMemoryStore } from '../../api/store-init.js';
|
|
13
13
|
import { isInitialized } from '../../host/project-identity.js';
|
|
14
14
|
import { hippoHomeDir } from '../../host/agent-homes.js';
|
|
15
|
-
import { memoryList } from '../../api/memories/memories.js';
|
|
15
|
+
import { memoryCountAll, memoryList } from '../../api/memories/memories.js';
|
|
16
16
|
import { cliApiContext, cliInitGlobal, cliSyncOptions } from './api-context.js';
|
|
17
17
|
import { isGitRepo } from '../../base/ports/git.js';
|
|
18
18
|
import { processGit } from '../../infra/git-runner.js';
|
|
@@ -28,6 +28,9 @@ import { learnFromRepo, skipLearnOnSharedStore } from './shared.js';
|
|
|
28
28
|
import { appendHookBlock, HOOK_MARKERS, HOOKS, hippoBlock } from '../hooks-install/instructions.js';
|
|
29
29
|
import { HIPPO_DIR } from '../../base/util/agent-homes.js';
|
|
30
30
|
import { SEED_DAYS_SCAN, SEED_DAYS_SINGLE } from './flag-defaults.js';
|
|
31
|
+
import { installLocalEmbedder } from './embedder-install.js';
|
|
32
|
+
import { loadConfig } from '../../host/config-file.js';
|
|
33
|
+
import { plural } from '../../base/util/format.js';
|
|
31
34
|
// An unreadable or vanished folder is expected while scanning; any other failure is worth a line.
|
|
32
35
|
const QUIET_SCAN_ERRORS = new Set(['EACCES', 'EPERM', 'ENOENT', 'ENOTDIR']);
|
|
33
36
|
function scanForGitRepos(rootDir, maxDepth = 2) {
|
|
@@ -157,6 +160,9 @@ async function initScannedRepos(scanDir, tenantId, flags) {
|
|
|
157
160
|
return;
|
|
158
161
|
}
|
|
159
162
|
console.log(`Found ${repos.length} repositories:\n`);
|
|
163
|
+
const stores = [hippoHomeDir(), ...repos.map((repo) => path.join(repo, HIPPO_DIR))];
|
|
164
|
+
const hadStores = stores.some((store) => isInitialized(store));
|
|
165
|
+
const embedderAdded = maybeInstallEmbedder(hippoHomeDir(), flags);
|
|
160
166
|
const globalRoot = initGlobalFirst();
|
|
161
167
|
const seedDays = numberFlag(flags, 'days') ?? SEED_DAYS_SCAN;
|
|
162
168
|
const machine = currentMachine();
|
|
@@ -170,6 +176,10 @@ async function initScannedRepos(scanDir, tenantId, flags) {
|
|
|
170
176
|
printAgentImport(agentImport, '');
|
|
171
177
|
}
|
|
172
178
|
console.log(`Global store: ${globalRoot}`);
|
|
179
|
+
if (embedderAdded && hadStores) {
|
|
180
|
+
console.log('Memories stored before this run have no vectors yet: run `hippo embed` in each project ' +
|
|
181
|
+
'and `hippo embed --global` to add them.');
|
|
182
|
+
}
|
|
173
183
|
if (initInstallsIntegrations(flags))
|
|
174
184
|
installScanHooks(repos);
|
|
175
185
|
if (!boolFlag(flags, 'no-schedule')) {
|
|
@@ -179,8 +189,11 @@ async function initScannedRepos(scanDir, tenantId, flags) {
|
|
|
179
189
|
}
|
|
180
190
|
async function initGlobalOnly(tenantId, flags) {
|
|
181
191
|
const globalRoot = hippoHomeDir();
|
|
192
|
+
const embedderAdded = maybeInstallEmbedder(globalRoot, flags);
|
|
182
193
|
if (isInitialized(globalRoot)) {
|
|
183
194
|
console.log('Already initialized global store at', globalRoot);
|
|
195
|
+
if (embedderAdded)
|
|
196
|
+
await printEmbedHint(globalRoot, tenantId, 'hippo embed --global');
|
|
184
197
|
}
|
|
185
198
|
else {
|
|
186
199
|
cliInitGlobal();
|
|
@@ -219,8 +232,11 @@ export async function handleInit({ hippoRoot, tenantId, flags }) {
|
|
|
219
232
|
return;
|
|
220
233
|
}
|
|
221
234
|
const alreadyExists = isInitialized(hippoRoot);
|
|
235
|
+
const embedderAdded = maybeInstallEmbedder(hippoRoot, flags);
|
|
222
236
|
if (alreadyExists) {
|
|
223
237
|
console.log('Already initialized at', hippoRoot);
|
|
238
|
+
if (embedderAdded)
|
|
239
|
+
await printEmbedHint(hippoRoot, tenantId, 'hippo embed');
|
|
224
240
|
}
|
|
225
241
|
else {
|
|
226
242
|
await initMemoryStore(cliApiContext(hippoRoot, tenantId));
|
|
@@ -247,6 +263,21 @@ export async function handleInit({ hippoRoot, tenantId, flags }) {
|
|
|
247
263
|
printAgentImport(await importForStore(hippoRoot, cliSyncOptions(tenantId, currentMachine())));
|
|
248
264
|
}
|
|
249
265
|
}
|
|
266
|
+
/** First in every init path: a killed install leaves no store to skip the first-run seed, and
|
|
267
|
+
* the memories init writes get vectors as they land. */
|
|
268
|
+
function maybeInstallEmbedder(configRoot, flags) {
|
|
269
|
+
if (boolFlag(flags, 'no-embeddings'))
|
|
270
|
+
return false;
|
|
271
|
+
return installLocalEmbedder(loadConfig(configRoot).embeddings);
|
|
272
|
+
}
|
|
273
|
+
/** The embedder arrived after this store already held memories, and those have no vectors yet. */
|
|
274
|
+
async function printEmbedHint(root, tenantId, command) {
|
|
275
|
+
const count = await memoryCountAll(cliApiContext(root, tenantId));
|
|
276
|
+
if (count > 0) {
|
|
277
|
+
const stored = plural(count, 'memory', 'memories');
|
|
278
|
+
console.log(` Run \`${command}\` to add vectors to the ${stored} stored before now.`);
|
|
279
|
+
}
|
|
280
|
+
}
|
|
250
281
|
/**
|
|
251
282
|
* Every write init makes into agent config (instruction blocks, hooks, plugins) is an automatic
|
|
252
283
|
* integration, so one switch skips them all.
|
|
@@ -11,6 +11,7 @@ import { boolFlag, numberFlag, stringFlagOrExit, hasFlag, } from './flag-values.
|
|
|
11
11
|
import { requireInit, resolveAuthRoot } from './shared.js';
|
|
12
12
|
import { errorMessage } from '../../base/util/log.js';
|
|
13
13
|
import { fail } from './exit.js';
|
|
14
|
+
import { embedderInstallAdvice } from './embedder-install.js';
|
|
14
15
|
const MAX_FAILED_SHOWN = 5;
|
|
15
16
|
const MAX_PAIRS_SHOWN = 15;
|
|
16
17
|
const PAIR_PREVIEW_CHARS = 90;
|
|
@@ -178,8 +179,7 @@ function readyEmbedProvider(ctx, given) {
|
|
|
178
179
|
return null;
|
|
179
180
|
}
|
|
180
181
|
if (embedProvider.kind === 'local') {
|
|
181
|
-
console.log(
|
|
182
|
-
console.log(' npm install @huggingface/transformers');
|
|
182
|
+
console.log(`Embeddings not available. To turn them on, ${embedderInstallAdvice()}`);
|
|
183
183
|
process.exitCode = 1;
|
|
184
184
|
}
|
|
185
185
|
else {
|
|
@@ -15,7 +15,7 @@ export const MEMORY_VERBS = {
|
|
|
15
15
|
repairsCodexWrapper: true,
|
|
16
16
|
scoped: true,
|
|
17
17
|
flags: {
|
|
18
|
-
switches: ['global', 'no-hooks', 'no-learn', 'no-schedule'],
|
|
18
|
+
switches: ['global', 'no-embeddings', 'no-hooks', 'no-learn', 'no-schedule'],
|
|
19
19
|
values: ['scan'],
|
|
20
20
|
numbers: ['days'],
|
|
21
21
|
},
|
|
@@ -28,6 +28,8 @@ export const MEMORY_VERBS = {
|
|
|
28
28
|
--no-hooks Skip auto-detecting and installing agent hooks
|
|
29
29
|
(HIPPO_SKIP_AUTO_INTEGRATIONS=1 does the same)
|
|
30
30
|
--no-schedule Skip auto-creating the machine-level daily runner
|
|
31
|
+
--no-embeddings Skip installing the local embedder (@huggingface/transformers)
|
|
32
|
+
(HIPPO_SKIP_EMBEDDER_INSTALL=1 does the same)
|
|
31
33
|
--no-learn Skip seeding memories from git history and importing
|
|
32
34
|
coding agents' own memories (every init imports those)`,
|
|
33
35
|
],
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
"id": "hippo-memory",
|
|
3
3
|
"name": "Hippo Memory",
|
|
4
4
|
"description": "One memory for every agent you'll ever use. Hippo writes what you teach a coding agent into a store in your repo, and your other agents read that same store.",
|
|
5
|
-
"version": "3.
|
|
5
|
+
"version": "3.8.0",
|
|
6
6
|
|
|
7
7
|
"configSchema": {
|
|
8
8
|
"type": "object",
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "hippo-memory",
|
|
3
|
-
"version": "3.
|
|
3
|
+
"version": "3.8.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "One memory for every agent you'll ever use. Hippo writes what you teach a coding agent into a store in your repo, and your other agents read that same store.",
|
|
6
6
|
"main": "index.ts",
|
package/openclaw.plugin.json
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
"id": "hippo-memory",
|
|
3
3
|
"name": "Hippo Memory",
|
|
4
4
|
"description": "One memory for every agent you'll ever use. Hippo writes what you teach a coding agent into a store in your repo, and your other agents read that same store.",
|
|
5
|
-
"version": "3.
|
|
5
|
+
"version": "3.8.0",
|
|
6
6
|
"configSchema": {
|
|
7
7
|
"type": "object",
|
|
8
8
|
"additionalProperties": false,
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "hippo-memory",
|
|
3
|
-
"version": "3.
|
|
3
|
+
"version": "3.8.0",
|
|
4
4
|
"description": "One memory for every agent you'll ever use. Hippo writes what you teach a coding agent into a store in your repo, and your other agents read that same store.",
|
|
5
5
|
"mcpName": "io.github.kitfunso/hippo-memory",
|
|
6
6
|
"type": "module",
|