feat: MeMesh v4.0.0 — cognitive middleware by kevintseng · Pull Request #17 · PCIRCLE-AI/memesh-llm-memory

kevintseng · 2026-04-19T18:24:49Z

Summary

MeMesh transforms from memory database to cognitive middleware — memory that auto-injects, auto-captures, auto-cleans, and auto-improves.

6 New Features

Recall Effectiveness Tracking — recall_hits/recall_misses columns track whether injected memories are actually used. Session-start records injected IDs, Stop hook checks transcript, analytics endpoint shows effectiveness %.

Continuous Recall (PreToolUse) — New hook on Edit/Write injects relevant memories when editing files. FTS5 + tag-based search, throttled per file per session.

BYOK Embedding — Multi-provider: OpenAI text-embedding-3-small (1536-dim), Ollama (768-dim), ONNX fallback (384-dim). Auto dimension migration on provider change.

Auto-Tagging with LLM — Generates 2-5 tags when remember() called without tags. Fire-and-forget.

Noise Filter — compressWeeklyNoise() archives old session_keypoint/commit into weekly summaries. Threshold: 20+, 7+ days old.

Memory Impact Score — Laplace-smoothed recall effectiveness as 6th scoring factor (10% weight).

Additional Changes

Skills rewritten to CLI-first with hooks documentation and auto-detect flow
Circular dependency between db.ts/embedder.ts resolved
Capabilities.embeddings correctly reports onnx for Anthropic (no embedding API)
RecallEffectiveness dashboard component with i18n (11 locales)
Scoring weights rebalanced for 6-factor model

Test Coverage

445 tests across 29 files. All passing.

2 DB migration tests (recall columns)
5 recall effectiveness tests
5 noise filter tests
8 auto-tagger tests (parseTags + integration)
5 pre-edit-recall hook tests
6 embedder tests (dimension + availability)
5 impact scoring tests

Pre-Landing Review

Comprehensive code review completed with 3 parallel agents:

Ripple Map: 14/14 exports fully synchronized, 0 unsynchronized
Reality Check: all imports verified, no dead wires
Honesty Audit: 0 type escapes, 0 SQL injection, all catch blocks justified
1 MINOR issue (circular dependency) — fixed in 11a6a90

Test plan

…ating The overwrite merge strategy previously archived the entity then called createEntity(), which has reactivation logic that un-archives and APPENDS new observations to the old ones. Now uses clearEntityData() to delete observations + tags (keeping the entity row) before re-populating, ensuring overwrite truly replaces content.

exportMemories() previously applied namespace filter AFTER the SQL LIMIT, so if limit=10 and the first 10 entities were all 'personal', requesting namespace='team' returned 0 results even if team entities existed. Now passes namespace directly to kg.search() which applies the filter in the SQL WHERE clause before LIMIT.

Add embedder.ts with local ONNX embedding generation using Xenova/all-MiniLM-L6-v2. Provides isEmbeddingAvailable(), embedText(), embedAndStore(), and vectorSearch() — all gracefully degrade when the package is missing. Fire-and-forget design keeps remember() synchronous.

- remember(): fire-and-forget embedAndStore() after entity creation (non-blocking, keeps function synchronous) - recallEnhanced(): vector search supplements FTS5 results in both LLM expansion path and Level 0 fallback path - Graceful degradation: if embeddings unavailable, search falls back to FTS5-only (no behavioral change for existing users)

Graph tab: force-directed canvas visualization of entity relationships with drag, hover tooltips, and type-based coloring. No external deps. Lessons tab: structured lesson_learned cards with parsed Error/Root cause/Fix/Prevention fields, severity coloring, and confidence badges. Both tabs include translations for all 11 supported languages.

…ph + Lessons - Neural embeddings: @xenova/transformers (all-MiniLM-L6-v2, 384-dim) integrated into remember (fire-and-forget) and recallEnhanced (hybrid search) - Fix overwrite import: clearEntityData() replaces archive+reactivate - Fix namespace export: filter at query level, not post-filter - Dashboard: 7 tabs (+ Graph with force-directed canvas, + Lessons with cards) - 402 tests across 25 files

Replace generic Inter/zinc/blue aesthetic with distinctive design: - Satoshi font (Fontshare) + Geist Mono (Google Fonts) - Cyan accent #00D6B4 replacing overused blue-500 - Compact 4px spacing, 8px radius, zero decoration - All hardcoded colors in LessonsTab/GraphTab replaced with design system tokens - DESIGN.md added as single source of truth for all visual decisions Co-Authored-By: Claude <noreply@anthropic.com>

…polish - FeedbackWidget component: type selection (Bug/Feature/Question), description textarea, system info toggle, opens pre-filled GitHub issue - Full i18n: 7 new keys across all 11 locales - Restore interaction feedback: header backdrop-filter, card/stat hover shadows, input focus ring, feedback button lift effect, connection dot glow Co-Authored-By: Claude <noreply@anthropic.com>

- FINDING-001/002/003: nav tabs min-height 44px, pagination buttons enlarged, border-bottom widened to 2px for better active indicator - FINDING-005: search tab shows hint text when no search performed (i18n: search.hint added to all 11 locales) Co-Authored-By: Claude <noreply@anthropic.com>

…lue metrics

…l 11 locales AnalyticsTab now fetches from both /v1/stats and /v1/analytics in parallel, rendering HealthScore, MemoryTimeline, ValueMetrics, and CleanupSuggestions components. Added 24 new i18n keys across all 11 locales (en, zh-TW, zh-CN, ja, ko, pt, fr, de, vi, es, th).

…e, type distribution

- HealthFactor: number → {score, weight, detail} object - Timeline: day → date field name - ValueMetrics: lessonsSaved → lessonsWithWarnings Co-Authored-By: Claude <noreply@anthropic.com>

…, recency heatmap, orphans - Type filter checkboxes: toggle visibility per entity type with colored dots - Search with highlight: 260px input, cyan glow ring on matches, auto-center single match - Ego graph: click node to focus on 1-degree neighborhood, banner with Show All - Recency heatmap: opacity based on last_accessed_at age (0.15-1.0 range) - Orphan indicator: dashed border for zero-relation nodes, 3rd stat card - Tooltip shows name, type, and age; edge labels hidden when >30 visible edges - Node labels only on hover/focus/match to reduce clutter - Performance: skip distant repulsion pairs for N>200 nodes - i18n: added graph.orphans/search/matches/focusMode/showAll/clickHint to all 11 locales

useEffect with [data] dependency fired while loading=true, when the canvas element wasn't in the DOM yet (loading spinner rendered instead). Added loading to dependency array and early return guard. Co-Authored-By: Claude <noreply@anthropic.com>

… ~2 seconds

CRITICAL: /v1/analytics staleEntities query now returns id + days_unused (was returning last_accessed_at without id — frontend contract mismatch) CRITICAL: Added IS NULL guard for last_accessed_at (test had it, prod didn't) MAJOR: Replaced (window as any).__graphReheat with proper global type declaration Found by comprehensive-code-review Dim 11 (Reality Check) + Dim 15 (Honesty Audit) Co-Authored-By: Claude <noreply@anthropic.com>

- SettingsTab: setLocale(value as any) → as Locale (proper type) - SettingsTab: llm: any → { provider, model?, apiKey? } (typed) - api.ts: ConfigData capabilities.llm: any → LlmConfig interface - api.ts: fetchLessons (result as any).entities → proper cast Zero `as any` remaining in dashboard/src/ Co-Authored-By: Claude <noreply@anthropic.com>

P2-1: Use SQLite datetime() for timestamp comparison instead of JS toISOString() — avoids format mismatch on boundary dates P2-2: Graph hit-testing now skips hidden nodes (type filter + ego mode) — prevents tooltip/click on invisible nodes P2-3: Coverage percentages use full type distribution total as denominator, not just top-8 slice — fixes inflated percentages Found by Codex gpt-5.4 code review Co-Authored-By: Claude <noreply@anthropic.com>

- New /v1/patterns endpoint: work schedule, tool preferences, focus areas, workflow metrics, strengths, learning areas - New memesh_user_patterns MCP tool (8th tool): returns patterns as markdown for AI agent context - Dashboard "Your Patterns" section with 24h heatmap, tool tags, workflow stats, strengths/learning split - i18n: 11 patterns.* keys across all 11 locales - Updated schema-export.ts + fixed test count (5 → 6 tools) Co-Authored-By: Claude <noreply@anthropic.com>

…17 endpoints)

- Extract computePatterns() to src/core/patterns.ts (DRY fix) - Both /v1/patterns and MCP user_patterns now share same logic - Consistent SQL ordering: ORDER BY hour for hours, ORDER BY dayNum for days - Always include dayNum in day distribution across both consumers - AnalyticsTab: symmetric .catch(() => null) on all API calls - Render stats/analytics sections independently when one fails - New tests/core/patterns.test.ts (5 tests) - Docs: 7->8 MCP tools, add user_patterns documentation - Smoke test: add dist/core/patterns.js to required files

P1: Workflow queries now search both session_keypoint AND session-insight (hooks use session-insight, not session_keypoint — metrics were always 0) P2: Added session-insight to AUTO_TYPES exclusion list (prevents synthetic entities from appearing in focus/strengths) P2: Work schedule uses localtime modifier for strftime (was UTC — peak hours shifted by timezone offset for non-UTC users) Found by Codex gpt-5.4 review Co-Authored-By: Claude <noreply@anthropic.com>

…ble deps - SQL: inline datetime() as SQL literal instead of JS string interpolation - Headers: X-Content-Type-Options, X-Frame-Options, Referrer-Policy - Deps: npm audit fix for known CVEs, override protobufjs>=7.5.5

- Rewrite CHANGELOG.md with Keep a Changelog format for all v3.x releases - Remove nonexistent PyPI badge and pip install reference from all READMEs - Replace Python SDK column with HTTP client example - Add real-world usage quotes section after Smart Features - Include repo/package note at end of CHANGELOG

Self-contained HTML demo of the Analytics dashboard with fake data, matching the real design system (Satoshi + Geist Mono, #00D6B4 accent). Lets potential users preview MeMesh without installing.

…gers, health score memesh/SKILL.md: - 6 → 8 tools (added learn + user_patterns with examples) - Added proactive learn triggers (after errors, debugging) - Added proactive user_patterns trigger (at session start) - Expanded entity types list (11 types) - Added namespace documentation - Added best practices for learn and patterns memesh-review/SKILL.md: - Now uses user_patterns for data-driven health report - Includes Health Score with 4 factors - Includes work patterns analysis - Identifies auto-generated noise ratio - Suggests knowledge gaps - Links to dashboard Analytics tab Co-Authored-By: Claude <noreply@anthropic.com>

Skills now teach agents to use CLI as primary interface (works everywhere) with MCP as optional faster path, and document what hooks already automate.

…s are used Session-start hook records injected entity IDs to temp file. Stop hook checks transcript for entity name matches and updates recall_hits/recall_misses columns. Analytics endpoint and dashboard show effectiveness metrics.

…to weekly summaries compressWeeklyNoise() groups auto-tracked entities older than 7 days by ISO week, creates weekly-summary entities, archives originals. Threshold: 20+ noise entities per week. Never touches decisions, patterns, lessons, or other intentional knowledge. Throttled to once per 24h via session-start hook.

Code review found hardcoded UI strings. Added recall.* keys to all 11 locales (en, zh-TW, zh-CN, ja, ko, pt, fr, de, vi, es, th).

New module auto-tagger.ts with parseTags + autoTagAndApply. Integrated into remember() as fire-and-forget: if no tags provided and LLM is configured, generates 2-5 tags (project:, topic:, tech:, etc.).

…diting files New pre-edit-recall.js hook on Edit/Write. Queries MeMesh for entities matching the file being edited (tag-based + FTS5). Throttled to max 1 recall per file per session via temp file. 5 hooks total now.

BYOK Embedding: OpenAI text-embedding-3-small (1536-dim), Ollama embedding models (768-dim), ONNX fallback (384-dim). Anthropic has no embedding API — correctly falls back to ONNX. Auto dimension migration: stores dim in metadata, drops/recreates entities_vec on provider change. Impact Score: Laplace-smoothed recall_hits/(hits+misses) as 6th scoring factor (10% weight). Entities with high recall effectiveness rise in search results; ignored entities fade.

Move getEmbeddingDimension() from embedder.ts to config.ts since it only depends on detectCapabilities(). Re-export from embedder.ts for backward compatibility. db.ts now imports from config.ts only.

Cognitive middleware milestone: recall effectiveness tracking, continuous recall, BYOK embedding, auto-tagging, noise filter, impact scoring.

+      // 3. FTS5 search on the basename (without extension)
+      const fileName = basename(filePath);
+      const fileNameNoExt = fileName.replace(/\.[^.]+$/, '');
+      const dirName = basename(dirname(filePath));


+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { openDatabase, closeDatabase, getDatabase } from '../../src/db.js';


1. Noise filter: add cutoff to 2nd query (prevent archiving recent entities) 2. Pre-edit recall: clear throttle file at session start 3. Auto-tagger: use provider-specific API key lookup 4. Analytics: COALESCE recall columns for pre-migration entities 5. Pre-edit recall: sanitize FTS5 query input (wrap in quotes) 6. Embedder: reset ONNX pipeline on failure (allow retry) 7. Pre-edit recall: remove WAL pragma on readonly connection 8. Noise filter: index summary entities in FTS5 9. Noise filter: fix ISO week comment (calendar week, not ISO) 10. Config endpoint: replace .passthrough() with .strip() 11. Noise filter: update existing summary instead of skipping 12. DB: log warning before dropping entities_vec on dimension change

kevintseng and others added 30 commits April 18, 2026 13:10

Merge branch 'main' into develop

bd7e0e4

feat(api): add /v1/analytics endpoint with health score, timeline, va…

cbbf42c

…lue metrics

feat(dashboard): add AnalyticsData type for /v1/analytics endpoint

50cfbc4

feat(dashboard): add HealthScore component with factor bars

faf8dae

feat(dashboard): add ValueMetrics component with coverage bars

91b3ddf

feat(dashboard): add CleanupSuggestions component with archive actions

e30ebce

feat(dashboard): add MemoryTimeline canvas sparkline component

45efb65

test(analytics): add tests for health score, stale detection, timelin…

c37af66

…e, type distribution

docs: add /v1/analytics endpoint to architecture and API reference

12457c9

fix(dashboard): align frontend types with actual /v1/analytics response

170c136

- HealthFactor: number → {score, weight, detail} object - Timeline: day → date field name - ValueMetrics: lessonsSaved → lessonsWithWarnings Co-Authored-By: Claude <noreply@anthropic.com>

fix(dashboard): use correct i18n key for lessons applied label

157b933

fix(dashboard): add cooling to force simulation — graph settles after…

1f61bac

… ~2 seconds

chore: add PRE_RELEASE_CHECKLIST.md to .gitignore

4e31323

Merge branch 'main' into develop

2f2730c

feat(api): add /v1/patterns endpoint for user work pattern analysis

15670fe

kevintseng and others added 22 commits April 19, 2026 13:22

feat(dashboard): add Your Patterns section to Analytics with i18n

be3e2d1

docs: add user_patterns tool and /v1/patterns endpoint (8 MCP tools, …

16d29ae

…17 endpoints)

Merge branch 'main' into develop

cacd375

docs: update README with v3.2.x features, new screenshots, 8 tools

4a2ffc1

docs: add static demo page for GitHub Pages

47b1e7f

Self-contained HTML demo of the Analytics dashboard with fake data, matching the real design system (Satoshi + Geist Mono, #00D6B4 accent). Lets potential users preview MeMesh without installing.

docs: update all 10 translated READMEs to match v3.2.x features

d3ccc68

docs: add v4.0 AI-native improvements plan skeleton

ddf0e71

docs(skills): CLI-first rewrite with hooks documentation

b25c12f

Skills now teach agents to use CLI as primary interface (works everywhere) with MCP as optional faster path, and document what hooks already automate.

fix(dashboard): add i18n for RecallEffectiveness component — 11 locales

1fa721a

Code review found hardcoded UI strings. Added recall.* keys to all 11 locales (en, zh-TW, zh-CN, ja, ko, pt, fr, de, vi, es, th).

feat(v4): auto-tagging — LLM generates tags when user provides none

17dd77b

New module auto-tagger.ts with parseTags + autoTagAndApply. Integrated into remember() as fire-and-forget: if no tags provided and LLM is configured, generates 2-5 tags (project:, topic:, tech:, etc.).

refactor: break circular dependency between db.ts and embedder.ts

11a6a90

Move getEmbeddingDimension() from embedder.ts to config.ts since it only depends on detectCapabilities(). Re-export from embedder.ts for backward compatibility. db.ts now imports from config.ts only.

chore: bump version to 4.0.0

f29aecd

Cognitive middleware milestone: recall effectiveness tracking, continuous recall, BYOK embedding, auto-tagging, noise filter, impact scoring.

github-advanced-security AI found potential problems Apr 19, 2026

View reviewed changes

kevintseng added 2 commits April 20, 2026 03:32

docs: add v4 adversarial review findings for fix session

cb7fb16

kevintseng merged commit 83f3c95 into main Apr 19, 2026
11 of 16 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: MeMesh v4.0.0 — cognitive middleware#17

feat: MeMesh v4.0.0 — cognitive middleware#17
kevintseng merged 54 commits intomainfrom
develop

kevintseng commented Apr 19, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

kevintseng commented Apr 19, 2026

Summary

6 New Features

Additional Changes

Test Coverage

Pre-Landing Review

Test plan

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants