memhouse 0.18.12 → 0.20.1

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 (169) hide show
  1. package/AGENTS.md +22 -151
  2. package/CHANGELOG.md +263 -29
  3. package/LICENSE +202 -22
  4. package/LICENSES/agentlytics-MIT.txt +21 -0
  5. package/LICENSES/memhouse-MIT-until-0.18.11.txt +22 -0
  6. package/LICENSES/models.dev-MIT.txt +22 -0
  7. package/NOTICE +28 -0
  8. package/README.md +42 -20
  9. package/SECURITY.md +21 -8
  10. package/bin/memhouse.js +2223 -311
  11. package/docs/README.md +11 -9
  12. package/docs/guides/admin-password.md +37 -10
  13. package/docs/guides/configuration.md +13 -6
  14. package/docs/guides/daemons.md +64 -3
  15. package/docs/guides/import-claude-ai.md +204 -0
  16. package/docs/guides/install.md +11 -6
  17. package/docs/guides/invite.md +21 -7
  18. package/docs/guides/operate.md +114 -7
  19. package/docs/guides/search-and-resume.md +72 -3
  20. package/docs/guides/share.md +91 -52
  21. package/docs/guides/storage.md +44 -4
  22. package/docs/guides/troubleshooting.md +121 -14
  23. package/docs/guides/uninstall.md +4 -3
  24. package/docs/guides/update.md +16 -0
  25. package/docs/guides/upgrade-to-0.20.md +188 -0
  26. package/docs/releases/README.md +2 -1
  27. package/docs/releases/v0.18.10.md +5 -5
  28. package/docs/releases/v0.18.11.md +3 -3
  29. package/docs/releases/v0.20.0.md +627 -0
  30. package/docs/releases/v0.20.1.md +114 -0
  31. package/docs/tutorials/01-first-house.md +10 -7
  32. package/docs/tutorials/02-join-a-house.md +24 -15
  33. package/docs/tutorials/03-share-your-memory.md +40 -31
  34. package/editors/antigravity.js +1 -80
  35. package/editors/base.js +463 -9
  36. package/editors/bridge.js +119 -0
  37. package/editors/claude.js +273 -105
  38. package/editors/codex.js +278 -52
  39. package/editors/copilot.js +1 -70
  40. package/editors/cursor.js +1 -75
  41. package/editors/derive-fingerprints.json +18 -0
  42. package/editors/harness-paths.js +69 -0
  43. package/editors/index.js +1 -20
  44. package/editors/normalise/agy.js +910 -0
  45. package/editors/normalise/copilot-cli.js +321 -0
  46. package/editors/normalise/cursor-agent.js +852 -0
  47. package/editors/normalise/cursor.js +474 -0
  48. package/editors/normalise/devin.js +575 -0
  49. package/editors/normalise/gemini-cli.js +602 -0
  50. package/editors/normalise/goose.js +673 -0
  51. package/editors/normalise/opencode.js +633 -0
  52. package/editors/normalise/vscode.js +549 -0
  53. package/editors/normalise/zed.js +473 -0
  54. package/editors/opencode-v4.js +119 -0
  55. package/editors/scope.js +14 -3
  56. package/editors/sessions-log.js +349 -0
  57. package/editors/sqlite.js +28 -1
  58. package/editors/vscode.js +1 -72
  59. package/editors/windsurf.js +1 -143
  60. package/examples/01-local-one-machine/README.md +24 -19
  61. package/examples/01-local-one-machine/run.sh +1 -1
  62. package/examples/02-existing-clickhouse/README.md +30 -22
  63. package/examples/02-existing-clickhouse/run.sh +5 -4
  64. package/examples/03-team-house/README.md +44 -37
  65. package/examples/03-team-house/run.sh +35 -18
  66. package/examples/04-self-hosted-team/README.md +29 -14
  67. package/examples/04-self-hosted-team/compose.yml +5 -2
  68. package/examples/04-self-hosted-team/smoke.sh +26 -12
  69. package/examples/README.md +8 -4
  70. package/examples/fixtures/README.md +4 -1
  71. package/examples/fixtures/make-sessions.js +8 -5
  72. package/memhouse/admin-secret.js +89 -24
  73. package/memhouse/argv-secrets.js +64 -0
  74. package/memhouse/channel.js +49 -9
  75. package/memhouse/codex-plugin.js +194 -0
  76. package/memhouse/delivery/AGENT-INSTALL-PROMPT.md +2 -1
  77. package/memhouse/delivery/AGENT-INSTALL.md +22 -11
  78. package/memhouse/delivery/INVITATION.md.tpl +44 -45
  79. package/memhouse/delivery/PROMPT.md +53 -5
  80. package/memhouse/delivery/UPGRADE.md.tpl +1 -1
  81. package/memhouse/delivery/codex/AGENTS-BLOCK.md +11 -0
  82. package/memhouse/delivery/codex/SKILL.md +50 -0
  83. package/memhouse/delivery/kernel-install.md +17 -9
  84. package/memhouse/delivery/plugin/.claude-plugin/plugin.json +2 -2
  85. package/memhouse/delivery/plugin/reference/HOUSE.md +168 -41
  86. package/memhouse/delivery/plugin/skills/access/SKILL.md +13 -5
  87. package/memhouse/delivery/plugin/skills/admin/SKILL.md +14 -6
  88. package/memhouse/delivery/plugin/skills/house/SKILL.md +25 -8
  89. package/memhouse/delivery/plugin/skills/recall/SKILL.md +66 -8
  90. package/memhouse/delivery/plugin/skills/sql/SKILL.md +66 -7
  91. package/memhouse/deploy.js +1 -1
  92. package/memhouse/flags.js +35 -18
  93. package/memhouse/help.js +37 -0
  94. package/memhouse/host.js +82 -2
  95. package/memhouse/house/HOUSE.md +2 -2
  96. package/memhouse/house/convert-profile.js +638 -0
  97. package/memhouse/house/convert-v3.js +742 -0
  98. package/memhouse/house/doctor-v3.js +324 -0
  99. package/memhouse/house/host-alias.js +85 -0
  100. package/memhouse/house/house.js +3 -3
  101. package/memhouse/house/migrate.js +2 -2
  102. package/memhouse/house/profile-dedupe.js +183 -0
  103. package/memhouse/house/profile-edges.js +554 -0
  104. package/memhouse/house/profile-house.js +430 -0
  105. package/memhouse/house/profile-rollup.js +190 -0
  106. package/memhouse/house/q-cli.js +863 -0
  107. package/memhouse/house/queries-v3.js +1013 -0
  108. package/memhouse/house/reconcile-v3.js +192 -0
  109. package/memhouse/house/records-to-profile.js +174 -0
  110. package/memhouse/house/records-to-rows.js +169 -0
  111. package/memhouse/house/relocate.js +2 -1
  112. package/memhouse/house/schema-choice.js +121 -0
  113. package/memhouse/house/schema-profile.js +290 -0
  114. package/memhouse/house/schema-profile.sql.tpl +398 -0
  115. package/memhouse/house/schema-v3.js +267 -0
  116. package/memhouse/house/schema-v3.sql.tpl +213 -0
  117. package/memhouse/import/claude-ai.js +420 -0
  118. package/memhouse/import/import.js +372 -0
  119. package/memhouse/import/pyjson.js +206 -0
  120. package/memhouse/import/records.js +64 -0
  121. package/memhouse/import/writer-profile.js +192 -0
  122. package/memhouse/import/writer-v3.js +240 -0
  123. package/memhouse/import/zip.js +112 -0
  124. package/memhouse/invitation.js +102 -0
  125. package/memhouse/invitefile.js +5 -2
  126. package/memhouse/plugin-copies.js +176 -0
  127. package/memhouse/provision.js +7 -2
  128. package/memhouse/release-hint.js +24 -0
  129. package/memhouse/resume.js +4 -4
  130. package/memhouse/server/api-v3.js +632 -0
  131. package/memhouse/server/dashboard-auth.js +181 -0
  132. package/memhouse/server/dashboard-port.js +91 -0
  133. package/memhouse/server/queries.js +30 -0
  134. package/memhouse/server/server.js +118 -20
  135. package/memhouse/service.js +1 -1
  136. package/memhouse/share.js +687 -1
  137. package/memhouse/shipper/adapter-capture.js +756 -0
  138. package/memhouse/shipper/capture.js +2571 -0
  139. package/memhouse/shipper/dedupe-profile.js +237 -0
  140. package/memhouse/shipper/dedupe-v3.js +1027 -0
  141. package/memhouse/shipper/forks.js +233 -0
  142. package/memhouse/shipper/log-adapter.js +219 -0
  143. package/memhouse/shipper/maintenance.js +49 -0
  144. package/memhouse/shipper/normalise-run.js +148 -0
  145. package/memhouse/shipper/passlog.js +68 -5
  146. package/memhouse/shipper/profile-capture.js +903 -0
  147. package/memhouse/shipper/ship.js +91 -8
  148. package/memhouse/shipper/snapshots.js +193 -0
  149. package/memhouse/shipper/source-roots.js +111 -0
  150. package/memhouse/version-notice.js +66 -0
  151. package/package.json +14 -7
  152. package/public/THIRD_PARTY_NOTICES.txt +2 -2
  153. package/public/assets/index-CcNnhfM3.js +78 -0
  154. package/public/index.html +1 -1
  155. package/ui/package-lock.json +56 -37
  156. package/ui/package.json +1 -0
  157. package/ui/src/App.jsx +29 -14
  158. package/ui/src/components/ChatSidebar.jsx +69 -12
  159. package/ui/src/lib/api.js +76 -0
  160. package/ui/src/lib/dashboard-token.js +41 -0
  161. package/ui/src/main.jsx +22 -5
  162. package/ui/src/pages/Dashboard.jsx +22 -36
  163. package/ui/third-party-notices.js +119 -0
  164. package/ui/vite.config.js +5 -1
  165. package/docs/releases/v0.18.12.md +0 -59
  166. package/memhouse/COMPETITION.md +0 -221
  167. package/memhouse/DESIGN.md +0 -222
  168. package/memhouse/RESUME-AND-UPDATE.md +0 -182
  169. package/public/assets/index-CnWzrjF3.js +0 -78
@@ -0,0 +1,194 @@
1
+ // `memhouse plugins install codex`: what Codex reads of memhouse, and only on request.
2
+ //
3
+ // Codex (0.165, checked against the request it sends) puts <codex home>/AGENTS.md into every
4
+ // prompt in full, and lists each skill under <codex home>/skills by its name and description,
5
+ // reading the body only when the skill is used. So the rules that must hold in every session go
6
+ // in a short block in AGENTS.md, and the read recipes in one skill, skills/memhouse.
7
+ //
8
+ // The block is marker-delimited. Install puts it at the top of the file, followed by one blank
9
+ // line, or creates the file with the block alone; a reinstall replaces it where it stands. Remove
10
+ // takes out the block and that one line, so the rest of the file is what it was, byte for byte;
11
+ // a file left empty is deleted, unless it is a symlink: then the target is emptied through it and
12
+ // the link stays. The skill directory carries an ownership file (OWNER_FILE): a
13
+ // skills/memhouse without it is somebody else's and is never replaced or removed.
14
+ //
15
+ // Nothing here writes under the Codex home except install, remove, and the refresh of a copy
16
+ // that install already put there (plugin-copies.js).
17
+
18
+ const fs = require('fs');
19
+ const os = require('os');
20
+ const path = require('path');
21
+
22
+ const SKILL = 'memhouse';
23
+ const OWNER_FILE = '.memhouse.json';
24
+ const BEGIN = '<!-- memhouse:begin';
25
+ const END = '<!-- memhouse:end -->';
26
+ const MARKERS = /^<!-- memhouse:(begin|end)\b[^\n]*$/gm;
27
+
28
+ /** The Codex home: CODEX_HOME when set, else ~/.codex. */
29
+ function codexHome(env = process.env) {
30
+ return env.CODEX_HOME || path.join(os.homedir(), '.codex');
31
+ }
32
+ const agentsFile = (cx) => path.join(cx, 'AGENTS.md');
33
+ const skillDir = (cx) => path.join(cx, 'skills', SKILL);
34
+ const real = (p) => { try { return fs.realpathSync(p); } catch { return path.resolve(p); } };
35
+
36
+ /**
37
+ * Where the block sits in `text`: { start, end, version }, or null when there is none.
38
+ * Throws when the markers do not make exactly one block, so nothing is written over a file
39
+ * whose block was damaged by hand.
40
+ */
41
+ function findBlock(text) {
42
+ const begins = []; const ends = [];
43
+ let m;
44
+ MARKERS.lastIndex = 0;
45
+ while ((m = MARKERS.exec(text))) (m[1] === 'begin' ? begins : ends).push(m.index);
46
+ if (!begins.length && !ends.length) return null;
47
+ if (begins.length !== 1 || ends.length !== 1 || ends[0] < begins[0]) {
48
+ throw new Error(`AGENTS.md holds ${begins.length} memhouse:begin and ${ends.length} memhouse:end markers, not one block — fix it by hand; nothing was changed`);
49
+ }
50
+ const nl = text.indexOf('\n', ends[0]);
51
+ const version = (/^<!-- memhouse:begin (\d+\.\d+\.\d+\S*)/.exec(text.slice(begins[0])) || [])[1] || null;
52
+ return { start: begins[0], end: nl === -1 ? text.length : nl + 1, version };
53
+ }
54
+
55
+ /** `text` with `block` in it: replaced where it stands, or put first with one blank line after. */
56
+ function withBlock(text, block) {
57
+ const b = findBlock(text);
58
+ if (b) return text.slice(0, b.start) + block + text.slice(b.end);
59
+ return text ? `${block}\n${text}` : block;
60
+ }
61
+
62
+ /** `text` without the block, and without the blank line install put after it. */
63
+ function withoutBlock(text) {
64
+ const b = findBlock(text);
65
+ if (!b) return text;
66
+ let rest = text.slice(b.end);
67
+ if (b.start === 0 && rest.startsWith('\n')) rest = rest.slice(1);
68
+ return text.slice(0, b.start) + rest;
69
+ }
70
+
71
+ /** A path for the text, with the home directory as ~. */
72
+ function shown(p) {
73
+ const h = os.homedir();
74
+ return p === h || p.startsWith(h + path.sep) ? `~${p.slice(h.length)}` : p;
75
+ }
76
+
77
+ /** A shell word: as is when it needs no quoting, else single-quoted. */
78
+ function shArg(s) {
79
+ return /^[A-Za-z0-9_@%+=:,./~-]+$/.test(s) ? s : `'${String(s).replace(/'/g, `'\\''`)}'`;
80
+ }
81
+
82
+ /** The `memhouse` on PATH, resolved, or null. */
83
+ function memhouseOnPath(env = process.env) {
84
+ for (const d of String(env.PATH || '').split(path.delimiter).filter(Boolean)) {
85
+ const f = path.join(d, 'memhouse');
86
+ try { fs.accessSync(f, fs.constants.X_OK); return real(f); } catch { /* not here */ }
87
+ }
88
+ return null;
89
+ }
90
+
91
+ /**
92
+ * How the block and the skill name the command: `memhouse` for the default instance, else with
93
+ * MEMHOUSE_HOME and the binary spelled out, each only where it differs from the default.
94
+ */
95
+ function invocation({ home, bin, defaultHome = path.join(os.homedir(), '.memhouse'), pathBin = memhouseOnPath() }) {
96
+ const parts = [];
97
+ if (home && real(home) !== real(defaultHome)) parts.push(`MEMHOUSE_HOME=${shArg(shown(home))}`);
98
+ parts.push(!bin || (pathBin && real(bin) === pathBin) ? 'memhouse' : shArg(shown(bin)));
99
+ return parts.join(' ');
100
+ }
101
+
102
+ function render(tpl, { mh, envFile }) {
103
+ return tpl.replace(/\{\{MH\}\}/g, mh).replace(/\{\{ENV_FILE\}\}/g, envFile);
104
+ }
105
+
106
+ function renderBlock({ deliveryDir, version, mh, envFile }) {
107
+ const body = render(fs.readFileSync(path.join(deliveryDir, 'codex', 'AGENTS-BLOCK.md'), 'utf-8'), { mh, envFile }).trim();
108
+ return `${BEGIN} ${version} — managed by \`memhouse plugins install codex\`; \`memhouse plugins remove codex\` takes it out -->\n${body}\n${END}\n`;
109
+ }
110
+
111
+ /** The skill directory's ownership record, or null when it is not memhouse's (or absent). */
112
+ function readOwner(dir) {
113
+ try {
114
+ const o = JSON.parse(fs.readFileSync(path.join(dir, OWNER_FILE), 'utf-8'));
115
+ return o && o.owner === 'memhouse' ? o : null;
116
+ } catch { return null; }
117
+ }
118
+
119
+ /**
120
+ * Write the block and the skill. Everything is checked before anything is written: a foreign
121
+ * skills/memhouse or a damaged block throws with the Codex home untouched.
122
+ * `onlyWhereInstalled`: the refresh — the block is rewritten only where it already is.
123
+ * @returns {{ file: string, created: boolean, block: boolean, dir: string, mh: string }}
124
+ */
125
+ function install({ codexHome: cx, home, bin, version, deliveryDir, pathBin, onlyWhereInstalled = false }) {
126
+ const dir = skillDir(cx);
127
+ if (fs.existsSync(dir) && !readOwner(dir)) {
128
+ throw new Error(`${shown(dir)} is not memhouse's (it has no ${OWNER_FILE}) — not replacing it; move it aside and install again`);
129
+ }
130
+ const file = agentsFile(cx);
131
+ let text = null;
132
+ try { text = fs.readFileSync(file, 'utf-8'); } catch (e) { if (e.code !== 'ENOENT') throw e; }
133
+ const mh = invocation({ home, bin, ...(pathBin !== undefined ? { pathBin } : {}) });
134
+ const envFile = shown(path.join(home, 'env'));
135
+ const writeBlock = !onlyWhereInstalled || (text !== null && findBlock(text) !== null);
136
+ const next = writeBlock ? withBlock(text || '', renderBlock({ deliveryDir, version, mh, envFile })) : text;
137
+ const skill = render(fs.readFileSync(path.join(deliveryDir, 'codex', 'SKILL.md'), 'utf-8'), { mh, envFile });
138
+
139
+ fs.rmSync(dir, { recursive: true, force: true });
140
+ fs.mkdirSync(dir, { recursive: true });
141
+ fs.writeFileSync(path.join(dir, 'SKILL.md'), skill);
142
+ fs.writeFileSync(path.join(dir, OWNER_FILE), `${JSON.stringify({ owner: 'memhouse', version, home, bin: bin || null }, null, 2)}\n`);
143
+ // In place, not a rename: an AGENTS.md that is a symlink (a dotfiles checkout) stays one.
144
+ if (writeBlock && next !== text) fs.writeFileSync(file, next);
145
+ return { file, created: text === null && writeBlock, block: writeBlock, dir, mh };
146
+ }
147
+
148
+ /**
149
+ * Take out the block and the skill — the skill only when it is memhouse's.
150
+ * @returns {{ block: boolean, fileDeleted: boolean, emptiedLink: boolean, skill: boolean, foreignSkill: string|null }}
151
+ */
152
+ function remove({ codexHome: cx }) {
153
+ const res = { block: false, fileDeleted: false, emptiedLink: false, skill: false, foreignSkill: null };
154
+ const file = agentsFile(cx);
155
+ let text = null;
156
+ try { text = fs.readFileSync(file, 'utf-8'); } catch (e) { if (e.code !== 'ENOENT') throw e; }
157
+ const next = text !== null && findBlock(text) ? withoutBlock(text) : null;
158
+ const dir = skillDir(cx);
159
+ const owned = !!readOwner(dir);
160
+ if (!owned && fs.existsSync(dir)) res.foreignSkill = dir;
161
+ if (next !== null) {
162
+ // Only a regular file is unlinked. Unlinking a symlink (a dotfiles checkout) would leave the
163
+ // block in its target, so the target is written through the link instead.
164
+ if (next === '' && !fs.lstatSync(file).isSymbolicLink()) { fs.rmSync(file); res.fileDeleted = true; }
165
+ else { fs.writeFileSync(file, next); res.emptiedLink = next === ''; }
166
+ res.block = true;
167
+ }
168
+ if (owned) { fs.rmSync(dir, { recursive: true }); res.skill = true; }
169
+ return res;
170
+ }
171
+
172
+ /** What is installed: the skill's owner record (or why not), and whether the block is there. */
173
+ function status({ codexHome: cx }) {
174
+ const dir = skillDir(cx);
175
+ const owner = readOwner(dir);
176
+ let block = null; let damaged = null;
177
+ try { block = findBlock(fs.readFileSync(agentsFile(cx), 'utf-8')); } catch (e) { if (e.code !== 'ENOENT') damaged = e.message; }
178
+ return { codexHome: cx, installed: !!owner, owner, foreignSkill: !owner && fs.existsSync(dir) ? dir : null, block: !!block, blockVersion: block ? block.version : null, damaged };
179
+ }
180
+
181
+ /**
182
+ * The copy to refresh for `version`, or null: installed, memhouse's, bound to `home`, and older.
183
+ */
184
+ function staleCopy({ codexHome: cx, home, version, compareVersions }) {
185
+ const owner = readOwner(skillDir(cx));
186
+ if (!owner || !owner.home || real(owner.home) !== real(home)) return null;
187
+ const c = compareVersions(owner.version, version);
188
+ return c === -1 || c === null ? { codexHome: cx, have: owner.version || null, home: owner.home, bin: owner.bin || null } : null;
189
+ }
190
+
191
+ module.exports = {
192
+ SKILL, OWNER_FILE, BEGIN, END, codexHome, agentsFile, skillDir, findBlock, withBlock, withoutBlock,
193
+ invocation, memhouseOnPath, renderBlock, readOwner, install, remove, status, staleCopy, shown,
194
+ };
@@ -57,7 +57,8 @@ already exist.
57
57
  Run `memhouse doctor` and report its output to the user. Every line should be a check
58
58
  mark. Then tell them:
59
59
 
60
- - where the dashboard is (`http://localhost:{{PORT}}`) and that `memhouse start` runs it
60
+ - that `memhouse start` runs the dashboard and `memhouse dashboard` opens it in their browser
61
+ (it needs a token only their account can read; never read or print the files that hold it)
61
62
  - that `memhouse search <terms>` searches every past session from every editor
62
63
  - that `memhouse plugins install claude` gives their agents /mem:recall, /mem:sql,
63
64
  /mem:house, /mem:access and /mem:admin — offer to run it
@@ -9,7 +9,8 @@ docker or podman exists — and states the one route that applies. This file is
9
9
  long-form version and assumes a reachable ClickHouse already exists, which is the case
10
10
  `deploy --local` was added to remove. Prereqs: Node >= 24 and a reachable
11
11
  ClickHouse >= 26.2 (local server, Cloud, or a kernel house — see
12
- `kernel-install.md` for the kernel path). No checkout required — memhouse is on npm.
12
+ `kernel-install.md` for the kernel path, which requires the Ultimagent kernel, not yet
13
+ public). No checkout required — memhouse is on npm.
13
14
 
14
15
  ## 1. Install
15
16
 
@@ -52,20 +53,25 @@ rooms, ships, and writes the config LAST — a hand-written file is read as trut
52
53
  every later command even when it is wrong, and an example URL pasted verbatim points
53
54
  at somebody's real house.
54
55
 
55
- With a credential the user already has on the house:
56
+ With a credential the user already has on the house, its password in `MEMHOUSE_PASSWORD` (set
57
+ by the user in their shell, or read from a file with `--password-file <file>`; never typed
58
+ into this conversation and never on the command line):
56
59
 
57
60
  ```bash
58
- memhouse install --url <house-url> --user <member> --password '<credential>' --db <house>
61
+ memhouse install --url <house-url> --user <member> --db <house>
59
62
  ```
60
63
 
61
- Or, holding an admin credential, mint the member and the house in one go:
64
+ Or, holding an admin credential, mint the member and the house in one go. The admin
65
+ password comes from `MEMHOUSE_ADMIN_PASSWORD`, which the user sets in their shell (or lends
66
+ with a secret manager), never from the command line and never through this conversation:
62
67
 
63
68
  ```bash
64
- memhouse install --url <house-url> \
65
- --admin-user <admin> --admin-password '<admin-credential>' \
66
- --db <house> --member <member> --member-password '<credential>'
69
+ memhouse install --url <house-url> --admin-user <admin> --db <house> --member <member>
67
70
  ```
68
71
 
72
+ Without `--member-password-file` (or `MEMHOUSE_MEMBER_PASSWORD`), install generates the
73
+ member's password and writes it to the config; nobody has to see it.
74
+
69
75
  The admin credential is used once and never stored. Ask the user for values; never
70
76
  invent them and never default to localhost:8123 — on many machines that is a real house
71
77
  belonging to someone else.
@@ -94,10 +100,12 @@ current-parse filter that any hand-written read of `messages` needs — the ship
94
100
  retains superseded parses under an `epoch`):
95
101
 
96
102
  ```bash
97
- curl -s -u "$MEMHOUSE_USER:$MEMHOUSE_PASSWORD" "$MEMHOUSE_URL/?database=$MEMHOUSE_DB" \
98
- --data-binary "SELECT source, count() FROM $(memhouse sessions-query) AS c GROUP BY source SETTINGS final=1, join_use_nulls=1 FORMAT PrettyCompact"
103
+ memhouse room-sql "SELECT source, count() FROM ($(memhouse sessions-query)) AS c GROUP BY source SETTINGS final=1, join_use_nulls=1"
99
104
  ```
100
105
 
106
+ `room-sql` reads the credentials itself, runs reads only, and resolves bare room names to
107
+ this member's.
108
+
101
109
  ## 5. Start the dashboard and the shipper loop
102
110
 
103
111
  ```bash
@@ -105,8 +113,11 @@ memhouse start # both as background daemons; UI is prebuilt in the packag
105
113
  memhouse status # daemons, connection, counts, freshness (--json for agents)
106
114
  ```
107
115
 
108
- The dashboard comes up on http://localhost:4640. `start` also runs the incremental
109
- re-ship loop, so this replaces any separate cron. `memhouse stop` ends both.
116
+ `memhouse dashboard` opens the dashboard in the user's browser on this machine. It requires a
117
+ token, kept in a mode-600 file in the memhouse home; the command opens a page holding it and
118
+ prints the token only to a terminal. Never read or print `~/.memhouse/dashboard-token` or
119
+ `~/.memhouse/dashboard.html`. `start` also runs the incremental re-ship loop, so this replaces
120
+ any separate cron. `memhouse stop` ends both.
110
121
 
111
122
  ## 6. Install the skills (optional, for Claude Code)
112
123
 
@@ -18,20 +18,43 @@ files:
18
18
  claude "Read MEMHOUSE-INVITATION.md and follow it. Ask me before each step that changes this machine."
19
19
  ```
20
20
 
21
- Any agent that can run shell commands works the same way; the rules it must keep are at
22
- the end of this page.
21
+ Any agent that can run shell commands works the same way; the rules it must keep come
22
+ first, just below.
23
+
24
+ ## For an agent following this page — read this first
25
+
26
+ You are installing memhouse for the person who handed you this file. Six rules; most of
27
+ them exist because an agent broke them:
28
+
29
+ 0. **Your credential is `{{FILE}}`, the file delivered with this page.** Look for it beside
30
+ this page, wherever the two were put: `ls {{FILE_ARG}}`, run in this page's directory,
31
+ confirms it is there. Do that before step 1.
32
+ 1. **Never open or print `{{FILE}}`, or any `MEMHOUSE_*` value.** `ls` is enough to confirm it
33
+ is there. No `cat`, no reading it with your file tool, no `echo $MEMHOUSE_PASSWORD`, no
34
+ `set -x`. This very session will be shipped into the house; a password you read is a
35
+ password archived.
36
+ 2. **Run the commands as written, in order.** Do not substitute `CREATE USER`, `GRANT` or any
37
+ SQL of your own; there is nothing to fix on the server from this side.
38
+ 3. **Ask before `memhouse install --env`.** It changes the invited password, deletes
39
+ `{{FILE}}`, and starts shipping this machine's transcripts. The person decides when that
40
+ happens.
41
+ 4. **A ✗ line is the end of that step, not an invitation to work around it.** Read the line
42
+ after it — every refusal names its remedy — do that or report it. `sudo` for `EACCES` is
43
+ the one you may apply yourself.
44
+ 5. **Report what `memhouse status` and `memhouse doctor` say**, verbatim, when you are done.
45
+ A green install is those two commands, not your summary of them.
23
46
 
24
47
  ## 0. Find your credential
25
48
 
26
- The install needs `{{FILE}}`, which was sent alongside this page. Confirm it is here first —
27
- run this from the same directory, and if it prints the filename you are ready:
49
+ {{EXPIRY}}The install needs `{{FILE}}`, the file delivered with this page. Confirm it is here first —
50
+ run this from the directory this page is in now, and if it prints the filename you are ready:
28
51
 
29
52
  ```
30
- ls invite-*.env
53
+ ls {{FILE_ARG}}
31
54
  ```
32
55
 
33
56
  If it is missing, it did not travel with this page; get it from whoever invited you before
34
- going on. Do not print its contents — the last line of it is a password.
57
+ going on. Do not open or print it: it holds a password.
35
58
 
36
59
  ## 1. Install memhouse
37
60
 
@@ -46,18 +69,16 @@ split: the person installs software, the agent does the rest.
46
69
 
47
70
  ## 2. Join the house
48
71
 
49
- From the directory holding `{{FILE}}`, just run memhouse — it finds the invitation and asks:
50
-
51
- ```
52
- memhouse
53
- ```
54
-
55
- (or, without the question: `memhouse install --env {{FILE}}`)
72
+ {{JOIN}}
56
73
 
57
- What that does, in order: connects to `{{URL}}` as `{{NAME}}`, **rotates your password to
58
- one only your machine knows**, creates your rooms, writes your config to `~/.memhouse/env`,
59
- deletes `{{FILE}}`, and starts shipping in the background. The password in the file stops
60
- working the moment install finishes, so a copy left in a chat is dead.
74
+ What that does, in order: connects to `{{URL}}` as `{{NAME}}`, creates your rooms, writes
75
+ your config to `~/.memhouse/env`, **changes your password to a new one only this machine
76
+ knows** and saves it there, deletes `{{FILE}}`, and starts shipping in the background. In
77
+ a terminal it asks before changing the password (say yes); run without a terminal, as an
78
+ agent runs it, it changes it without asking. The password in the file stops working once
79
+ that is done, so a copy left in a chat is dead. `--keep-password` keeps the invited one
80
+ instead, and whoever invited you then still knows it. If the change fails, the install
81
+ still completes, keeps `{{FILE}}`, and says to run `memhouse passwd`.
61
82
 
62
83
  ## 3. Check it is working
63
84
 
@@ -73,12 +94,12 @@ happen.
73
94
 
74
95
  ## 4. What you own, and who can see it
75
96
 
76
- Your memory lives in five tables named for you inside `{{DB}}` — `{{DB}}.{{NAME}}_messages`,
77
- `{{DB}}.{{NAME}}_sessions`, `{{DB}}.{{NAME}}_tool_calls` and two bookkeeping tables — and you
78
- hold exactly one grant, on `{{DB}}.{{NAME}}_*`. Housemates cannot read your rooms, list
79
- them, or grant them to anyone; you cannot read theirs. `memhouse whoami --json` reads that
80
- grant back from the server. What can always see everything is the account that administers
81
- the ClickHouse, which is {{INVITER}}'s — the same as any database you use at work.
97
+ {{OWNED}}
98
+
99
+ Housemates cannot read your tables, list them, or grant them to anyone; you cannot read
100
+ theirs. `memhouse whoami --json` reads your grants back from the server. What can always see
101
+ everything is the account that administers the ClickHouse, which is {{INVITER}}'s — the same
102
+ as any database you use at work.
82
103
 
83
104
  Everything your editors write to disk ships verbatim: prompts, replies, tool calls and their
84
105
  arguments, including anything an agent ever pasted into a session. The house is as
@@ -127,25 +148,3 @@ Every refusal says what to do next. The two you might meet: `EACCES` on install
127
148
  `sudo`, and `needed rights this credential does not hold` means the grant on the server is
128
149
  narrower than the one memhouse issues — ask {{INVITER}} to run `memhouse install --print-sql
129
150
  --member {{NAME}}` and apply what it prints.
130
-
131
- ## For an agent following this page
132
-
133
- You are installing memhouse for the person who handed you this file. Five rules; three of
134
- them exist because an agent broke them:
135
-
136
- 0. **Your credential is `{{FILE}}` in the directory this page is in.** If `Read
137
- MEMHOUSE-INVITATION.md` is all you were given, `ls invite-*.env` beside it is the file
138
- the steps refer to; confirm it is there before step 1.
139
- 1. **Never print `{{FILE}}` or any `MEMHOUSE_*` value.** No `cat`, no `echo $MEMHOUSE_PASSWORD`,
140
- no `set -x`. This very session will be shipped into the house; a password printed here is
141
- a password archived.
142
- 2. **Run the commands as written, in order.** Do not substitute `CREATE USER`, `GRANT` or any
143
- SQL of your own; there is nothing to fix on the server from this side.
144
- 3. **Ask before `memhouse install --env`.** It rotates the credential, deletes `{{FILE}}`,
145
- and starts shipping this machine's transcripts. The person decides when that happens.
146
- 4. **A ✗ line is the end of that step, not an invitation to work around it.** Read the line
147
- after it — every refusal names its remedy — do that or report it. `sudo` for `EACCES` is
148
- the one you may apply yourself.
149
- 5. **Report what `memhouse status` and `memhouse doctor` say**, verbatim, when you are done.
150
- A green install is those two commands, not your summary of them.
151
-
@@ -1,7 +1,9 @@
1
1
  # memhouse — system-prompt snippet
2
2
 
3
3
  Paste (or import) this into an agent's system prompt to make memhouse its
4
- long-term conversation memory.
4
+ long-term conversation memory. `memhouse prompt` prints it rendered for this install —
5
+ its house, its env file, and the blocks for its schema (3: harness-sessions-sql's profile tables; 2:
6
+ the 0.18 rooms).
5
7
 
6
8
  ---
7
9
 
@@ -13,10 +15,18 @@ editors), across all of THEIR machines, stored in a ClickHouse database called
13
15
  **{{DB}}** (their "house"). The house outlives the transcripts on disk: editors
14
16
  compact and delete local session files after weeks, and the house is then the only
15
17
  copy.
16
- Connection: read `{{ENV_FILE}}` (`MEMHOUSE_URL/USER/PASSWORD/DB`); query over
17
- HTTP with `curl -u "$MEMHOUSE_USER:$MEMHOUSE_PASSWORD" "$MEMHOUSE_URL/?database=$MEMHOUSE_DB"`
18
- and always add `SETTINGS final=1, join_use_nulls=1` to reads — the second matters
19
- wherever the session rollup is used (see below).
18
+ <!-- schema 3 -->
19
+ Connection: the `memhouse` CLI reads `{{ENV_FILE}}` itself — you never need the
20
+ credentials. This house is on **schema 3**, harness-sessions-sql's profile: per member,
21
+ `session_parts` (one row per message part), `session_usage` (one row per usage record),
22
+ `calls` (one row per tool call) and `sessions` (one row per session, with exact totals).
23
+ <!-- end schema 3 -->
24
+ <!-- schema 2 -->
25
+ Connection: the `memhouse` CLI reads `{{ENV_FILE}}` itself — you never need the
26
+ credentials. Query with `memhouse room-sql` (SQL on stdin, reads only; bare room names
27
+ resolve to yours) and always add `SETTINGS final=1, join_use_nulls=1` to reads — the
28
+ second matters wherever the session rollup is used (see below).
29
+ <!-- end schema 2 -->
20
30
 
21
31
  **When to reach for it — before claiming ignorance.** If the user refers to past
22
32
  work that is not in your current context ("that session where…", "how did I solve
@@ -35,6 +45,31 @@ FIRST. Only say you don't know after a search comes back empty.
35
45
  - `/mem:admin` — server-wide administration; needs an administrator credential.
36
46
 
37
47
  Without skills, query directly.
48
+ <!-- schema 3 -->
49
+
50
+ **The named queries.** `memhouse q <name> --json` runs the house's own read layer — the
51
+ same queries the dashboard uses — and prints one JSON object. A session is
52
+ `<harness>:<session_id>` (the `ref` every result carries, e.g. `claude-code:6b1f…`).
53
+
54
+ - Find sessions about a topic (every term must occur in one message part, its text or a
55
+ tool's output; a "quoted phrase" as written): `memhouse q search clickhouse "authentication failed" --json`
56
+ - Read around a hit: `memhouse q window <ref> --at <message_id> --json` (3 parts before,
57
+ 12 after); a whole session: `memhouse q session <ref> --json` (paged with `--cursor`)
58
+ - Recent sessions: `memhouse q recent --limit 20 --since 7d --json`
59
+ - Numbers: `memhouse q spend --by model`, `q models`, `q tools`, `q activity --by day`,
60
+ `q hosts`, `q coverage`; `memhouse q` lists every name and flag
61
+ - Filters: `--harness`, `--project`, `--folder`, `--host`, `--since`, `--until`
62
+
63
+ **Raw SQL** only when no named query fits: `memhouse room-sql "<SELECT …>"` runs one
64
+ read-only statement with the bare names `sessions`, `session_parts`, `session_usage`,
65
+ `calls` (and the rest) resolved to this member's tables. Read them `FINAL` with
66
+ `is_deleted = 0 AND removed = 0`; identify a session by its five-column key `(host, harness,
67
+ harness_path, session_id, incarnation)`; read a
68
+ session's parts by its key, in `order_key` order; take totals and tokens from `sessions`,
69
+ never by summing parts or usage (usage needs its flags, and a `per_record` response counts
70
+ once); count messages with `kind = 'text'` that are not reverted or retracted.
71
+ <!-- end schema 3 -->
72
+ <!-- schema 2 -->
38
73
 
39
74
  **Table names.** The rooms are `messages`, `sessions`, `tool_calls` in the connection's
40
75
  database — unless this is a shared house, where they carry the member's own prefix
@@ -69,8 +104,20 @@ the retained epochs are the only place that content still exists.
69
104
  (the rollup applies the current-parse filter itself)
70
105
  - Replay one session: `SELECT role, text FROM messages
71
106
  WHERE session_id = '<id>' AND <CUR> ORDER BY seq SETTINGS final=1, join_use_nulls=1`
107
+ <!-- end schema 2 -->
72
108
 
73
109
  **Rules.**
110
+ <!-- schema 3 -->
111
+ - Memory is READ-ONLY for you: `memhouse q` and `memhouse room-sql` only read (the server
112
+ refuses a write on that connection). Ingestion belongs to the memhouse shipper alone;
113
+ membership administration goes through the `memhouse` CLI (`/mem:access`).
114
+ - Quote retrieved content as *the user's past sessions*, and cite the `ref`
115
+ (`<harness>:<session_id>`) when the user may want to dig deeper — `memhouse resume <ref>`
116
+ prints the command that reopens it.
117
+ - A housemate's memory is readable only where they granted it: add `--member <name>` to a
118
+ named query. An empty result means "nothing visible", not "nothing ever happened".
119
+ <!-- end schema 3 -->
120
+ <!-- schema 2 -->
74
121
  - Memory is READ-ONLY for you: never INSERT/ALTER/DROP the ROOMS (sessions, messages,
75
122
  tool_calls) — ingestion belongs to the memhouse shipper alone. The one exception is
76
123
  membership administration through the `memhouse` CLI: `/mem:access` mints a user and
@@ -81,4 +128,5 @@ the retained epochs are the only place that content still exists.
81
128
  shared with this credential (`/mem:access` on their side). Query a shared house by
82
129
  qualified names — `sam.messages` — with the same CUR filter. An empty result
83
130
  means "nothing visible", not "nothing ever happened".
131
+ <!-- end schema 2 -->
84
132
  - Do not paste credentials from `{{ENV_FILE}}` into responses, commits, or logs.
@@ -44,7 +44,7 @@ minutes, a fresh pass.
44
44
 
45
45
  - **Reading a housemate.** In `/mem:recall`, a friend's memory is `{{DB}}.<friend>_messages`
46
46
  — no database switch. `/mem:house` lists who can read yours.
47
- - **The dashboard** (`memhouse start`, then the printed URL) is faster: the tables it reads
47
+ - **The dashboard** (`memhouse start`, then `memhouse dashboard`) is faster: the tables it reads
48
48
  are now filled by your own shipper at the end of each pass.
49
49
  - **Nothing to re-share.** Grants you gave or received were re-expressed on the new names.
50
50
 
@@ -0,0 +1,11 @@
1
+ ## memhouse: past agent sessions
2
+
3
+ This machine's agent sessions (Codex, Claude Code and other editors) are kept in a memhouse
4
+ house. For a question about earlier work (what was done, when, in which hours, what it cost,
5
+ how something was fixed), use the `memhouse` skill before saying you do not know.
6
+
7
+ - Never read, print or echo `{{ENV_FILE}}`, and never print a `MEMHOUSE_*` value: they hold the
8
+ house's password, and this conversation may be shipped into the house. `{{MH}}` reads its
9
+ own configuration.
10
+ - `MEMHOUSE_URL` is the house (ClickHouse). `MEMHOUSE_PORT` is the local dashboard's port, not
11
+ the house's.
@@ -0,0 +1,50 @@
1
+ ---
2
+ name: memhouse
3
+ description: "Answer from past agent sessions kept in memhouse (Codex, Claude Code and other editors): what was worked on and when, which hours or days, spend and models, tools used, how something was fixed, a past session's transcript, a housemate's shared sessions. Read-only memhouse commands. Use before saying you do not know about earlier work."
4
+ ---
5
+
6
+ # memhouse: read past sessions
7
+
8
+ Every command here only reads. `{{MH}}` reads its own configuration: never read or print
9
+ `{{ENV_FILE}}` or any `MEMHOUSE_*` value.
10
+
11
+ Start with `{{MH}} q schema`. The recipes below are for schema 3. On 2 (a house still on the
12
+ 0.18 rooms), `{{MH}} prompt` prints the recipes for it.
13
+
14
+ ## Named queries
15
+
16
+ `{{MH}} q <name> --json` prints one JSON object. A session is `<harness>:<session_id>`, the
17
+ `ref` every result carries.
18
+
19
+ - Sessions about a topic (every term in one message; a "quoted phrase" as written):
20
+ `{{MH}} q search clickhouse "authentication failed" --json`
21
+ - Around a hit: `{{MH}} q window <ref> --at <message_id> --json`. A whole session:
22
+ `{{MH}} q session <ref> --json`, paged with `--cursor`.
23
+ - Recent sessions: `{{MH}} q recent --limit 20 --since 7d --json`
24
+ - Which hours or days: `{{MH}} q activity --by hour --grain usage --tz <IANA zone> --json`
25
+ counts messages and tokens by the hour they happened; `--by day`, `--by dow`, `--by day,host`.
26
+ - Spend and models: `{{MH}} q spend --by model --since 30d --json`, `{{MH}} q models --json`
27
+ - Tools: `{{MH}} q tools --limit 25 --json`; one tool's calls: `{{MH}} q tool <name> --json`
28
+ - Machines: `{{MH}} q hosts --json`. What the house holds: `{{MH}} q coverage --json`
29
+ - Filters on most names: `--harness`, `--project`, `--folder`, `--host`, `--since`, `--until`.
30
+ `{{MH}} q` lists every name and flag.
31
+
32
+ ## A housemate's sessions
33
+
34
+ Add `--member <name>` to a named query to read sessions a housemate shared with you.
35
+ `{{MH}} share --list` names who shared with you. An empty result means nothing is visible,
36
+ not that nothing happened.
37
+
38
+ ## Raw SQL, when no named query fits
39
+
40
+ `{{MH}} room-sql "<SELECT …>"` runs one read-only statement. The bare names `sessions`,
41
+ `session_parts`, `session_usage` and `calls` resolve to your tables (`--member <name>` for a
42
+ housemate's). Read them `FINAL` with `is_deleted = 0 AND removed = 0`; a session is
43
+ `(host, harness, harness_path, session_id, incarnation)`; take totals from `sessions`, never by
44
+ summing parts or usage.
45
+
46
+ ## Answering
47
+
48
+ Answer from what the commands return, cite the `ref` of each session used, and say so when a
49
+ search finds nothing. `{{MH}} resume <ref>` prints the command that reopens a session. Cost is
50
+ derived from token counts: an unpriced model is unknown, not free.
@@ -1,13 +1,19 @@
1
1
  # memhouse — install as a kernel agency
2
2
 
3
+ **Requires the Ultimagent kernel, which is not yet public.**
4
+
3
5
  How to run memhouse as an **agency** on an ultimagent kernel — a ClickHouse server
4
6
  (a **town**) promoted into a realm — instead of a plain ClickHouse. Same flow proven
5
- for the agentlytics agency (`agency/AGENCY.md`); the agency is named **`memhouse`** and
7
+ for the agentlytics agency; the agency is named **`memhouse`** and
6
8
  its house is the **`mem`** database (CH identifiers can't carry a dash, and the owning
7
9
  role kept the longer name — `memhouse_root`). What lands is a **house** (the `mem`
8
10
  database) with a **resident** (the shipper — `kind = "worker"`, `on = "loop"`) — that
9
11
  pairing is the agency. Residents write; routines read, and the session rollup is a
10
- routine. Terms: `../../TERMINOLOGY.md`.
12
+ routine. Terms:
13
+
14
+ - **realm**: one kernel deployment; **town**: the ClickHouse server behind it.
15
+ - **house**: a database; **room**: a table in it; **member**: a user with grants on their rooms.
16
+ - **agency**: a house plus the **residents** that fire and write in it; a **routine** is called, returns, and writes nothing.
11
17
 
12
18
  **One set of rooms per member.** Each member owns `sessions_<them>`, `messages_<them>`,
13
19
  `tool_calls_<them>` and holds grants on those and nothing else, so isolation is an
@@ -36,13 +42,16 @@ rotate on first connect (`issue-credential{user:'memhouse_root'}`).
36
42
 
37
43
  ```bash
38
44
  npm install -g memhouse
39
- memhouse install --yes \
45
+ printf '%s' "$CREDENTIAL" | memhouse install --yes \
40
46
  --url https://<kernel-host>:8443 \
41
47
  --user memhouse_root \
42
- --password <credential-from-provision> \
48
+ --password-file - \
43
49
  --db mem
44
50
  ```
45
51
 
52
+ `$CREDENTIAL` is the one-time credential from provisioning; reading it on stdin keeps it
53
+ off the command line.
54
+
46
55
  That writes `~/.memhouse/env`, applies the schema, and runs the first ship.
47
56
  `memhouse start` then keeps it fresh on a 300s loop.
48
57
 
@@ -92,10 +101,9 @@ and documented in `SHARING.md` — they are not how isolation works.
92
101
 
93
102
  ```bash
94
103
  memhouse stats # per-source counts as the owner
95
- # as a member: the rollup resolves to alice's own rooms, so counts are hers alone
96
- curl -s -u "alice:<pw>" "$MEMHOUSE_URL/?database=mem" \
97
- --data-binary "SELECT count() FROM $(memhouse sessions-query) AS c SETTINGS final=1, join_use_nulls=1"
104
+ # as a member, on alice's own machine (her install holds her credential): the rollup
105
+ # resolves to her own rooms, so counts are hers alone
106
+ memhouse room-sql "SELECT count() FROM ($(memhouse sessions-query)) AS c SETTINGS final=1, join_use_nulls=1"
98
107
  # and the team room narrows rather than denying — alice sees herself plus whoever granted her
99
- curl -s -u "alice:<pw>" "$MEMHOUSE_URL/?database=mem" \
100
- --data-binary "SELECT user_id, count() FROM all_messages GROUP BY user_id SETTINGS final=1"
108
+ memhouse room-sql "SELECT user_id, count() FROM all_messages GROUP BY user_id SETTINGS final=1"
101
109
  ```
@@ -1,11 +1,11 @@
1
1
  {
2
2
  "name": "mem",
3
3
  "description": "Conversation memory for AI agents over the memhouse typed ClickHouse store: recall past sessions and answer from them, run analytics, check the house, bring people in, and administer the server. Skills install as /mem:recall, /mem:sql, /mem:house, /mem:access, and /mem:admin.",
4
- "version": "0.18.12",
4
+ "version": "0.20.0",
5
5
  "author": {
6
6
  "name": "Ramazan Polat"
7
7
  },
8
- "homepage": "https://github.com/agent-realm/memhouse",
8
+ "homepage": "https://memhouse.io",
9
9
  "keywords": [
10
10
  "memory",
11
11
  "clickhouse",