feat(intelligence): add Graph Cohesion

[aashir-athar]

Summary

Adds a new read-only "Cohesion" tab to the Intelligence view: clustering-coefficient analysis of the memory knowledge graph. Where the Centrality lens answers "which entities are important", this lens answers "how tightly knit is the neighbourhood around each entity" — and surfaces a structural signal neither centrality nor a frequency sort can reveal: brokers.

A broker (structural hole) is an entity whose neighbours are not connected to each other — it's the sole link holding otherwise-separate clusters together (local clustering ≈ 0). These are the single points of failure / brokerage opportunities in the user's accumulated memory.

Design

• Pure deterministic engine (lib/memory/graphCohesion.ts): treats the (subject)-[predicate]->(object) triples as an undirected simple graph (direction dropped, parallel edges collapsed, self-loops dropped) and computes:
  • per-node local clustering coefficient C(v) = 2·triangles / (deg·(deg-1)),
  • triangleCount, averageClustering (mean of C over degree≥2 nodes), and transitivity (the global clustering coefficient, 3·triangles / connected-triples),
  • findBrokers() — ranks the loosest-neighbourhood entities.
  • No React, no RPC, no clock, no RNG. The result depends only on graph structure, never on insertion order — and averageClustering is summed in canonical (sorted) order so it is byte-identical across input permutations despite IEEE-754 non-associativity.
• Zero new core surface: composes the already-shipped memoryGraphQuery / memoryListNamespaces JSON-RPC wrappers. Read-only — recomputed live from the graph, never persisted.
• Container/presentational split; the container guards load-on-mount with a monotonic request token (out-of-order responses can't overwrite the latest). i18n across all 13 locales.

Test plan

• vitest — 33 tests (engine: empty/triangle/path/4-cycle/star/diamond fixtures with hand-computed clustering, triangle, avg & transitivity values; self-loop drop; parallel-edge & direction collapse; malformed-row drop; no case-folding; byte-identical determinism across permutations; broker ranking & limits — plus api facade, panel states + broker badge + no-brokers note, container load/namespace-requery/error)
• tsc --noEmit — clean
• eslint — 0 errors
• prettier --check — clean
• i18n coverage gate — EXIT 0, no missing/extra/drifted keys across 13 locales

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added a Graph Cohesion tab in Intelligence with namespace selector, loading skeletons, retryable error alerts, empty-state messaging, metric tiles (entities/connections/triangles), average clustering/transitivity caption, and a ranked brokers table/badges.

• Documentation

  • Added Graph Cohesion UI translations across many languages.

• Tests

  • Added end-to-end tests and unit suites covering cohesion computation, broker ranking, API loading, and UI states.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a deterministic graph-cohesion engine, a graphCohesion API facade, a stateful GraphCohesionTab and presentational GraphCohesionPanel, tests for computation and UI, Intelligence page wiring for a new "cohesion" tab, and i18n entries across locales.

Changes

Graph Cohesion Feature

Layer / File(s)	Summary
Core graph cohesion computation app/src/lib/memory/graphCohesion.ts, app/src/lib/memory/graphCohesion.test.ts	Deterministic cohesion metrics: builds undirected adjacency, drops self-loops/collapses parallel edges, counts triangles, computes per-node degree/triangles/localClustering, aggregates edge/triangle counts, transitivity, and deterministic averageClustering; exports CohesionNode, CohesionResult, computeGraphCohesion, and findBrokers. Tests cover basic shapes, diamond graph, normalization, determinism, sorting, and broker limits.
API facade and Intelligence page wiring app/src/services/api/graphCohesionApi.ts, app/src/services/api/graphCohesionApi.test.ts, app/src/pages/Intelligence.tsx	graphCohesionApi.loadCohesion(namespace?) wraps memoryGraphQuery and returns computeGraphCohesion results; loadNamespaces forwards memoryListNamespaces. Intelligence page adds 'cohesion' tab variant, tabs config entry, and mounts GraphCohesionTab. API tests verify namespace passthrough, result transformation, RPC rejection propagation, and namespace listing.
Container tab and tests app/src/components/intelligence/GraphCohesionTab.tsx, app/src/components/intelligence/GraphCohesionTab.test.tsx	Stateful tab loads cohesion and namespace lists, swallows namespace-list failures, uses a monotonic requestId to ignore stale responses, re-queries on namespace change, and wires onRetry to reload the current namespace. Tests verify initial load, namespace-driven reload, and error rendering.
Presentational panel and tests app/src/components/intelligence/GraphCohesionPanel.tsx, app/src/components/intelligence/GraphCohesionPanel.test.tsx	Presentational React panel supporting loading skeleton, error alert with optional retry, empty state, and success view showing metric tiles (entities/connections/triangles), summary caption (average clustering, transitivity), and a broker-ranking table with clustering badges and "no brokers" note when applicable.
Internationalization support app/src/lib/i18n/en.ts, app/src/lib/i18n/chunks/{ar,bn,de,en,es,fr,hi,id,it,ko,pt,ru,zh-CN}-1.ts	Adds memory.tab.cohesion and a graphCohesion.* block with UI strings for title/intro, loading/error/retry/empty states, namespace labels, metrics (entities, connections, triangles), summary caption (average clustering/transitivity), broker messaging, and table column headers across locales.

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant GraphCohesionTab
  participant graphCohesionApi
  participant memoryGraphQuery
  participant computeGraphCohesion
  participant GraphCohesionPanel
  User->>GraphCohesionTab: Open Intelligence / select cohesion tab
  GraphCohesionTab->>graphCohesionApi: loadCohesion(namespace)
  graphCohesionApi->>memoryGraphQuery: memoryGraphQuery(namespace)
  memoryGraphQuery-->>graphCohesionApi: GraphRelation[]
  graphCohesionApi->>computeGraphCohesion: computeGraphCohesion(relations)
  computeGraphCohesion-->>graphCohesionApi: CohesionResult
  graphCohesionApi-->>GraphCohesionTab: CohesionResult
  GraphCohesionTab->>GraphCohesionPanel: render(result, loading=false)
  GraphCohesionPanel-->>User: display metrics, summary, brokers

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• tinyhumansai/openhuman#2378: Overlapping i18n edits for German locale (adds translation entries similar to this PR).

Suggested reviewers

• graycyrus

Poem

🐰 I hopped through nodes with tiny paws,

counted ties and checked the laws,
triangles, brokers, links aligned—
cohesion maps the paths I find,
a little hop, and insights pause.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 46.15% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(intelligence): add Graph Cohesion' clearly and concisely describes the main change—adding a new Graph Cohesion feature to the Intelligence component. It directly matches the PR's primary objective.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@app/src/lib/memory/graphCohesion.test.ts`:
- Around line 206-218: The inline comment in the test "sorts nodes by clustering
DESC, then degree DESC, then id ASC" is incorrect: update the note that
currently says "B,C also 1 here" to reflect that B and C have localClustering
2/3 (degree 3) and only A and D have clustering 1; edit the comment near the
computeGraphCohesion call or the rel(...) list so it accurately documents the
diamond shape and that the ones array (derived from r.nodes.filter(...).map(n =>
n.id)) should be ['A','D'].

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 074eeae0-b6d9-49cc-8b4e-49110efce73e

📥 Commits

Reviewing files that changed from the base of the PR and between 42888ae and 71bc99a.

📒 Files selected for processing (23)

• app/src/components/intelligence/GraphCohesionPanel.test.tsx
• app/src/components/intelligence/GraphCohesionPanel.tsx
• app/src/components/intelligence/GraphCohesionTab.test.tsx
• app/src/components/intelligence/GraphCohesionTab.tsx
• app/src/lib/i18n/chunks/ar-1.ts
• app/src/lib/i18n/chunks/bn-1.ts
• app/src/lib/i18n/chunks/de-1.ts
• app/src/lib/i18n/chunks/en-1.ts
• app/src/lib/i18n/chunks/es-1.ts
• app/src/lib/i18n/chunks/fr-1.ts
• app/src/lib/i18n/chunks/hi-1.ts
• app/src/lib/i18n/chunks/id-1.ts
• app/src/lib/i18n/chunks/it-1.ts
• app/src/lib/i18n/chunks/ko-1.ts
• app/src/lib/i18n/chunks/pt-1.ts
• app/src/lib/i18n/chunks/ru-1.ts
• app/src/lib/i18n/chunks/zh-CN-1.ts
• app/src/lib/i18n/en.ts
• app/src/lib/memory/graphCohesion.test.ts
• app/src/lib/memory/graphCohesion.ts
• app/src/pages/Intelligence.tsx
• app/src/services/api/graphCohesionApi.test.ts
• app/src/services/api/graphCohesionApi.ts

✅ Files skipped from review due to trivial changes (4)

• app/src/lib/i18n/chunks/it-1.ts
• app/src/lib/i18n/en.ts
• app/src/lib/i18n/chunks/fr-1.ts
• app/src/lib/i18n/chunks/es-1.ts

🚧 Files skipped from review as they are similar to previous changes (14)

• app/src/components/intelligence/GraphCohesionTab.test.tsx
• app/src/pages/Intelligence.tsx
• app/src/lib/i18n/chunks/bn-1.ts
• app/src/services/api/graphCohesionApi.ts
• app/src/lib/i18n/chunks/id-1.ts
• app/src/lib/i18n/chunks/ar-1.ts
• app/src/services/api/graphCohesionApi.test.ts
• app/src/lib/i18n/chunks/en-1.ts
• app/src/lib/i18n/chunks/ru-1.ts
• app/src/components/intelligence/GraphCohesionTab.tsx
• app/src/lib/i18n/chunks/zh-CN-1.ts
• app/src/components/intelligence/GraphCohesionPanel.test.tsx
• app/src/lib/memory/graphCohesion.ts
• app/src/components/intelligence/GraphCohesionPanel.tsx

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Inline comment contradicts the assertion below it.

The comment claims B,C also 1 here, but in this diamond B and C have degree 3 and cluster at 2/3 — only A and D are at 1, which is exactly what the ones assertion verifies. The misleading note could prompt a future reader to "fix" a correct test.

✏️ Suggested comment correction

-      rel('B', 'C'), // triangle A-B-C (clustering 1 for A; B,C also 1 here)
+      rel('B', 'C'), // triangle A-B-C; A & D cluster at 1, B & C at 2/3 (diamond spine)
       rel('B', 'D'),
       rel('C', 'D'), // diamond

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	it('sorts nodes by clustering DESC, then degree DESC, then id ASC', () => {
	const r = computeGraphCohesion([
	rel('A', 'B'),
	rel('A', 'C'),
	rel('B', 'C'), // triangle A-B-C (clustering 1 for A; B,C also 1 here)
	rel('B', 'D'),
	rel('C', 'D'), // diamond
	]);
	// top entries are the clustering-1 nodes; A before D by id at equal degree.
	expect(r.nodes[0].localClustering).toBe(1);
	const ones = r.nodes.filter(n => n.localClustering === 1).map(n => n.id);
	expect(ones).toEqual(['A', 'D']);
	});
	it('sorts nodes by clustering DESC, then degree DESC, then id ASC', () => {
	const r = computeGraphCohesion([
	rel('A', 'B'),
	rel('A', 'C'),
	rel('B', 'C'), // triangle A-B-C; A & D cluster at 1, B & C at 2/3 (diamond spine)
	rel('B', 'D'),
	rel('C', 'D'), // diamond
	]);
	// top entries are the clustering-1 nodes; A before D by id at equal degree.
	expect(r.nodes[0].localClustering).toBe(1);
	const ones = r.nodes.filter(n => n.localClustering === 1).map(n => n.id);
	expect(ones).toEqual(['A', 'D']);
	});

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@app/src/lib/memory/graphCohesion.test.ts` around lines 206 - 218, The inline
comment in the test "sorts nodes by clustering DESC, then degree DESC, then id
ASC" is incorrect: update the note that currently says "B,C also 1 here" to
reflect that B and C have localClustering 2/3 (degree 3) and only A and D have
clustering 1; edit the comment near the computeGraphCohesion call or the
rel(...) list so it accurately documents the diamond shape and that the ones
array (derived from r.nodes.filter(...).map(n => n.id)) should be ['A','D'].