Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

perf(console): memory map embedding layout 28x faster, one layout per frame (bench-memmap)

ruv67ce7a2c18bf
diff --git a/plugins/ruflo-console/hooks/gfx/memmap.ts b/plugins/ruflo-console/hooks/gfx/memmap.ts
index 23a1ca02c1..d3e4d460cb 100644
--- a/plugins/ruflo-console/hooks/gfx/memmap.ts
+++ b/plugins/ruflo-console/hooks/gfx/memmap.ts
@@ -39,15 +39,32 @@ const unit = (text: string, seed: number): number => hash32(text, seed) / 0x1_00
/** Namespaces in a fixed order (by name), so a namespace keeps its colour and its place whatever else is listed. */
export const spacesOf = (entries: readonly { namespace: string }[]): string[] => [...new Set(entries.map(entry => entry.namespace))].sort()
+/** The two hyperplanes' ±1 signs by dimension index, grown on demand: hashing the index per entry per dimension was the whole cost of an embedding layout. */
+const signs: [Int8Array, Int8Array] = [new Int8Array(0), new Int8Array(0)]
+
+function signsFor(length: number): [Int8Array, Int8Array] {
+ if (signs[0].length < length) {
+ const size = Math.max(length, 384)
+
+ signs[0] = Int8Array.from({ length: size }, (_, i) => (hash32(String(i), 1) & 1 ? 1 : -1))
+ signs[1] = Int8Array.from({ length: size }, (_, i) => (hash32(String(i), 2) & 1 ? 1 : -1))
+ }
+
+ return signs
+}
+
/** A vector onto the plane through two fixed ±1 hyperplanes seeded by the dimension index; tanh keeps it inside 0..1. */
export function projectVector(vector: readonly number[]): { x: number; y: number } {
+ const [sa, sb] = signsFor(vector.length)
let a = 0
let b = 0
- vector.forEach((value, i) => {
- a += (hash32(String(i), 1) & 1 ? 1 : -1) * value
- b += (hash32(String(i), 2) & 1 ? 1 : -1) * value
- })
+ for (let i = 0; i < vector.length; i++) {
+ const value = vector[i] as number
+
+ a += (sa[i] as number) * value
+ b += (sb[i] as number) * value
+ }
const scale = Math.sqrt(Math.max(1, vector.length)) / 2
@@ -57,11 +74,29 @@ export function projectVector(vector: readonly number[]): { x: number; y: number
/** Every entry is embedded and carries its vector: the only case the map may call 'embedding'. */
export const modeOf = (entries: readonly MapEntry[]): MapMode => (entries.length > 0 && entries.every(entry => entry.vector !== undefined && entry.vector.length > 1) ? 'embedding' : 'hash')
-/** The plane: positions in 0..1 for each entry, by `modeOf`. Deterministic: the same entries land in the same places. */
+const laidOut = new WeakMap<readonly MapEntry[], { mode: MapMode; points: MapPoint[] }>()
+
+/**
+ * The plane: positions in 0..1 for each entry, by `modeOf`. Deterministic: the same entries land in the same places. Remembered per
+ * entries array (a probe hands the same array to every frame until it refreshes), so the picture and the rows of one frame lay out once.
+ */
export function layout(entries: readonly MapEntry[]): { mode: MapMode; points: MapPoint[] } {
+ const known = laidOut.get(entries)
+
+ if (known !== undefined) return known
+
+ const placed = layoutOf(entries)
+
+ laidOut.set(entries, placed)
+
+ return placed
+}
+
+function layoutOf(entries: readonly MapEntry[]): { mode: MapMode; points: MapPoint[] } {
const mode = modeOf(entries)
const spaces = spacesOf(entries)
const n = spaces.length
+ const slot = new Map(spaces.map((space, i) => [space, i]))
// Ring radius and cluster radius, in -1..1 units: clusters of neighbouring namespaces on the ring just touch.
const ring = n === 1 ? 0 : 0.6
const spread = n === 1 ? 0.85 : Math.min(0.4, 0.9 * ring * Math.sin(Math.PI / n))
@@ -71,7 +106,7 @@ export function layout(entries: readonly MapEntry[]): { mode: MapMode; points: M
if (mode === 'embedding') return { ...meta, ...projectVector(entry.vector as readonly number[]) }
- const angle = (Math.max(0, spaces.indexOf(entry.namespace)) / Math.max(1, n)) * Math.PI * 2 - Math.PI / 2
+ const angle = ((slot.get(entry.namespace) ?? 0) / Math.max(1, n)) * Math.PI * 2 - Math.PI / 2
const around = unit(entry.key, 3) * Math.PI * 2
const reach = Math.sqrt(unit(entry.key, 4)) * spread
diff --git a/plugins/ruflo-console/scripts/bench-memmap.mjs b/plugins/ruflo-console/scripts/bench-memmap.mjs
new file mode 100644
index 0000000000..27c51fad89
--- /dev/null
+++ b/plugins/ruflo-console/scripts/bench-memmap.mjs
@@ -0,0 +1,91 @@
+// @ts-check
+/**
+ * Memory map cost: the data reader (`memory list` JSON -> entries), the layout, the picture and the whole section render, at 1k and
+ * 10k entries (the real probe caps at MAP_LIMIT = 500; the larger sizes show what an uncapped caller would pay). Median and p99
+ * wall time per call, approximate bytes allocated per call (heapUsed delta after gc(); run with --expose-gc, else n/a).
+ * Embedding rows are synthetic 384-dim vectors: the CLI's list does not print vectors today, so that column is the worst case.
+ * NODE_OPTIONS=--expose-gc npx -y tsx plugins/ruflo-console/scripts/bench-memmap.mjs [iterations]
+ */
+import { mapEntriesOf } from '../hooks/data/memmap.ts'
+import { layout, memmapPicture, spacesOf } from '../hooks/gfx/memmap.ts'
+import { newState } from '../hooks/state.ts'
+import { memmapPictures, memmapRows } from '../hooks/views/memmap.ts'
+
+const N = Math.max(5, Number(process.argv[2]) || 30)
+const SPACES = ['auth', 'notes', 'patterns', 'tasks', 'claude-memories', 'feedback', 'sessions', 'routing']
+const element = (/** @type {string} */ type) => (/** @type {Record<string, unknown>} */ props) => ({ type, props })
+const kit = /** @type {never} */ ({ Box: element('Box'), Text: element('Text'), Button: element('Button'), Raster: element('Raster') })
+const act = /** @type {never} */ (new Proxy({}, { get: () => () => undefined }))
+const gc = /** @type {(() => void) | undefined} */ (globalThis.gc)
+const ms = (/** @type {bigint} */ start) => Number(process.hrtime.bigint() - start) / 1e6
+
+const entriesOf = (/** @type {number} */ n, /** @type {boolean} */ embedded) =>
+ Array.from({ length: n }, (_, i) => ({
+ key: `entry-${i}-${(i * 2654435761) % 99991}`,
+ namespace: /** @type {string} */ (SPACES[i % SPACES.length]),
+ hasVector: true,
+ accessCount: i % 13,
+ ...(embedded && { vector: Array.from({ length: 384 }, (_, d) => Math.sin(i * 0.37 + d)) }),
+ }))
+
+const time = (/** @type {() => unknown} */ fn) => {
+ for (let i = 0; i < 3; i++) fn()
+
+ const samples = []
+
+ for (let i = 0; i < N; i++) {
+ const start = process.hrtime.bigint()
+
+ fn()
+ samples.push(ms(start))
+ }
+
+ samples.sort((a, b) => a - b)
+
+ let bytes = 'n/a'
+
+ if (gc !== undefined) {
+ gc()
+ const before = process.memoryUsage().heapUsed
+
+ for (let i = 0; i < 10; i++) fn()
+ bytes = `${Math.round((process.memoryUsage().heapUsed - before) / 10 / 1024)} KiB`
+ }
+
+ return `median ${(samples[Math.floor(N / 2)] ?? 0).toFixed(3).padStart(9)} ms · p99 ${(samples[Math.min(N - 1, Math.floor(N * 0.99))] ?? 0).toFixed(3).padStart(9)} ms · ~${bytes}`
+}
+
+const row = (/** @type {string} */ name, /** @type {() => unknown} */ fn) => console.log(` ${name.padEnd(34)} ${time(fn)}`)
+
+for (const size of [1000, 10_000]) {
+ console.log(`\n${size} entries (${N} runs each)`)
+
+ for (const embedded of [false, true]) {
+ const mode = embedded ? 'embedding' : 'hash'
+ const entries = entriesOf(size, embedded)
+ const json = JSON.stringify(entries.map(e => ({ key: e.key, namespace: e.namespace, hasEmbedding: true, accessCount: e.accessCount, ...(e.vector && { embedding: e.vector }) })))
+ const { points } = layout(entries)
+ const spaces = spacesOf(entries)
+ const hits = new Set(points.slice(0, 20).map(p => `${p.namespace}/${p.key}`))
+ const state = newState({ boot: false })
+
+ state.probes.set('memmap', { value: entries, error: null, okAtMs: 4_000 })
+
+ const ctx = /** @type {never} */ ({ kit, state, act, columns: 100, nowMs: 5_000, pictures: new Map() })
+
+ row(`[${mode}] mapEntriesOf (parse)`, () => mapEntriesOf(json))
+ // Cold rows hand a fresh array each call (layout is remembered per array); the copy is ~0.1 ms at 10k and is inside the figure.
+ row(`[${mode}] layout (cold)`, () => layout([...entries]))
+ row(`[${mode}] memmapPicture`, () => memmapPicture(points, spaces, hits, 100))
+ row(`[${mode}] frame: pictures+rows (cold)`, () => {
+ state.probes.set('memmap', { value: [...entries], error: null, okAtMs: 4_000 })
+ memmapPictures(state, 100)
+ memmapRows(ctx)
+ })
+ state.probes.set('memmap', { value: entries, error: null, okAtMs: 4_000 })
+ row(`[${mode}] frame: pictures+rows (warm)`, () => {
+ memmapPictures(state, 100)
+ memmapRows(ctx)
+ })
+ }
+}
diff --git a/plugins/ruflo-console/tests/memmap.spec.ts b/plugins/ruflo-console/tests/memmap.spec.ts
index eb1c615088..20af4d921b 100644
--- a/plugins/ruflo-console/tests/memmap.spec.ts
+++ b/plugins/ruflo-console/tests/memmap.spec.ts
@@ -172,3 +172,30 @@ describe('the view', () => {
expect(texts(memmapRows(ctxOf(state))).join('\n')).toContain('read counts n/a')
})
})
+
+describe('the optimised projection and layout cache', () => {
+ it('projects exactly as the per-dimension hash definition does, at any length', () => {
+ for (const length of [2, 7, 384, 1536]) {
+ const v = Array.from({ length }, (_, i) => Math.cos(i * 1.7))
+ let a = 0
+ let b = 0
+
+ v.forEach((value, i) => {
+ a += (hash32(String(i), 1) & 1 ? 1 : -1) * value
+ b += (hash32(String(i), 2) & 1 ? 1 : -1) * value
+ })
+
+ const scale = Math.sqrt(Math.max(1, length)) / 2
+
+ expect(projectVector(v)).toEqual({ x: 0.5 + 0.5 * Math.tanh(a / scale), y: 0.5 + 0.5 * Math.tanh(b / scale) })
+ }
+ })
+
+ it('lays an array out once and gives a new array its own layout', () => {
+ const list = entries()
+
+ expect(layout(list)).toBe(layout(list))
+ expect(layout([...list])).not.toBe(layout(list))
+ expect(layout([...list])).toEqual(layout(list))
+ })
+})