v12.6.0 - Memnex visual memory workspace and recall-chain hardening

v12.6.0 - Visual memory workspace and recall-chain hardening

Released 2026-07-16.

This release packages two connected improvements: a navigable 2D/3D memory
workspace and repairs across the memory_save, memory_recall, graph
expansion, representation, session, and rules-layer paths. The public viewer
remains local-first and static: the exporter reads SQLite in read-only mode and
writes generated files only to the output directory.

What changed since the previous Memnex release

The comparison baseline is the previous public LLK-LL/Memnex v0.3.0
release (main commit 1b6280b, 2026-06-27). The old local/package label
total-agent-memory refers to this same project and is retained only for
backward compatibility.

Area	Memnex v0.3.0	Memnex v12.6.0
Export	Read-only static graph export with a 2D Memory Galaxy and a separate basic 3D sphere viewer	Embedded graph data, inline viewer modules, 2D/3D coexistence bridge, and one workspace-level view switch
Navigation	Galaxy, solar-system, and planet-satellite exploration in the 2D surface	The same 2D navigation plus 2D-focus-to-3D synchronization, 3D navigation tree, projected minimap, and Knowledge Solar System surface
3D	Node spheres, links, filters, pointer drag, wheel zoom, and node inspection	Observatory and fly-through modes, graph-derived planet systems, real satellites, NASA texture assets, asteroid belt, comets, LOD/instancing diagnostics, and reset/focus controls
Interaction	Mouse/pointer-based graph interaction	Pointer/keyboard interaction plus a worker-backed MediaPipe gesture runtime with stable hand association, hysteresis, dropout recovery, and diagnostics
Memory engine	File-backed memory vault and graph-viewer documentation	Project/alias-aware save and recall, agent-namespace isolation, relevance-gated retrieval, routed graph expansion, multi-representation filtering, phase-scoped rules, and recall telemetry

The comparison is intentionally limited to capabilities verified in the
current source trees. The viewer does not upload memory data or camera frames.

CodeGraph chain map

The current visualization path was re-indexed with CodeGraph 0.9.9 and then
confirmed against the source files.

CLI / export command
  -> main()
  -> export_viewer()
  -> connect_readonly()
  -> load_graph()
  -> write_graph_json() + embed_graph_data()
  -> copy_assets() + inline_viewer_modules()

index.html
  -> viewer.js:init()
  -> graph conversion / filtering / 2D rendering
  -> initMemoryUniverse3DCoexistence()
       -> setActiveView("2d" | "3d")
       -> applyCurrent2DFocusTo3D()
       -> mountKnowledgeSolar()
            -> knowledge-solar-system iframe route
                 -> loadCodexKnowledgePlanetSystems()
                 -> createKnowledgeSolarSystemSourceFromGraphs()
                 -> createKnowledgeSolarLayout()
                 -> createKnowledgeSolarPlanetVisualPlans()
                 -> Three.js render loop
                 -> gesture control runtime

The gesture branch is:

Start gesture control
  -> getUserMedia()
  -> frame scheduler
  -> gesture worker
  -> MediaPipe inference
  -> gesture interpreter
  -> rotate / pan / zoom action
  -> orbit controls

Fly-through mode
  -> same worker/inference pipeline
  -> left-hand flight gesture controller
  -> forward + speed multiplier
  -> right-hand look controller
  -> yaw/pitch update in solar flight controller

Panel reference

2D Memory Galaxy

• Header and breadcrumb: Return to the previous scope, show the current
  galaxy/system context, and search the visible memory graph.
• View Controls: Camera mode, speed, auto-rotate, motion trails, and comet
  visibility. These affect the visualization only.
• Filters: Search nodes, choose node types, select graph layers, adjust
  relationship/metric modes, and tune relevance, recency, and node strength.
• Performance HUD: FPS, frame time, CPU load, JavaScript memory estimate,
  GPU estimate/renderer, and visible node/edge counts.
• Live Graph Scope: Counts for systems, nodes, direct connections, and
  inferred links in the active graph.
• Minimap: Shows the current 2D viewport and provides a compact way to
  jump around a large graph.
• Inspector: Overview, Nodes, and Connections tabs show the selected
  system/node, its counts and members, and related edges. The prompt area
  stages a selected node as context for a future agent action.

3D Memory Universe and Knowledge Solar System

• 2D / 3D switch: Changes the main surface without losing the current
  graph scope.
• Knowledge Solar System mode (K): Opens the graph-derived solar route.
• Observatory mode (O): Keeps the camera in orbit/browse mode for
  selecting planet systems, planets, and satellites.
• Fly-through mode (S): Enters bounded first-person movement around the
  solar scene. The current orbit/inspect state is restored on exit.
• Center and reset (U): Returns the solar camera and mode state to a
  known center position.
• Navigation panel: Lists galaxy/system/planet relationships and lets the
  user move between scopes.
• Projected minimap: Projects the 3D scene into a compact navigation view;
  in fly-through mode it also shows the camera marker, heading, orbit tracks,
  and asteroid belt boundary.
• Inspection overlays: Show the current target, relationship traces,
  satellite pick targets, runtime diagnostics, and scene performance.

Operation reference

Input	Operation
Search input	Filter visible nodes by text.
Type/layer checkboxes	Include or exclude node types and graph layers.
Relevance/recency/strength sliders	Recompute the visible graph and layout.
Left-drag in 2D/3D orbit view	Rotate the view.
Middle-drag	Pan the view.
Wheel	Zoom in or out in orbit/browse mode.
Click a node or satellite	Select and inspect the item.
Right-click	Focus the camera on the clicked point when supported.
Double-click a system/planet	Drill into the corresponding scope.
Inspector tabs	Switch between overview, nodes, and connections.
K, O, S, U buttons	Switch Knowledge Solar, observatory, fly-through, and reset actions.
Keyboard arrows / escape	Pan or exit an active inspection where the route supports it.

Gesture reference

Gesture control is opt-in. The browser asks for camera permission only after
the user presses Start gesture control. The published screenshots in this
release intentionally hide the camera preview.

Observatory / orbit mode

Gesture	Operation
One open palm, move	Rotate the orbit view.
One pinched hand, move	Pan the view.
One pointing-up hand, move	Pan the view through the robust pointing-up path; this is also the geometric fallback when classifier evidence is incomplete.
Two valid hands, change separation	Zoom in when the hands move apart; zoom out when they move together. The transform uses an accumulation window and dead zone to suppress jitter.
Closed fist	Pause gesture actions and hold the current view.
Unknown handedness, stale frame, or hand loss	Ignore or reset the active intent until a fresh stable hand association is confirmed.

Fly-through mode

Gesture	Operation
Left open palm	Move forward.
Left palm moves upward/downward	Increase/decrease the cruise-speed multiplier while the left open palm remains active.
Right open palm	Look around with the high-gain look mapping.
Right pointing-up	Look around with the lower-gain precision mapping.
Left hand disappears or becomes invalid	Stop forward motion after the short dropout tolerance.
No stable right-hand look gesture	Hold the current heading; it does not inject a camera jump.

The solar route ignores orbit gestures while fly-through is active and sends
the flight-specific actions to the bounded solar flight controller. Leaving
fly-through restores the saved orbit/inspection state.

Memory save and recall repairs

The release also includes the current working-tree repairs outside the viewer:

• Project identity: canonical project names, Windows paths, and registered
  aliases resolve to one identity; project filters accept aliases but never
  widen to another project.
• Save path: sessions normalize project context, stale sessions can be
  closed automatically, and optional representation/enrichment work remains
  queueable without making the core save dependent on an LLM response.
• Recall path: FTS, semantic, multi-representation, episode, and graph
  tiers receive the same project and agent-namespace boundary. A final
  post-fusion filter removes candidates that violate that boundary.
• Relevance: high-signal query terms are extracted, matched terms and
  coverage are returned, and the configurable relevance gate prevents a
  merely similar result from displacing a low-signal query.
• Graph expansion: query routing selects applicable graph families and
  returns explicit applied/skipped diagnostics instead of hiding the decision.
• Rules layer: phase/project-scoped rule context is preserved through the
  recall chain; rule effectiveness counts explicitly rated outcomes rather
  than treating every fire as a success or failure.
• Observability: recall responses and monitor summaries retain routing,
  project alias, relevance, graph-family, and retrieval-tier diagnostics.

The operational map and troubleshooting entry point are in
MEMORY_SYSTEM_FEATURES_TROUBLESHOOTING.md.

Quick start

Export a local viewer from a memory database:

python src/tools/memory_graph_viewer_export.py --output .\graph-viewer-output

Open graph-viewer-output\index.html. For a large graph, use
--max-nodes, --max-edges, and --min-edge-weight to reduce browser load.
The 3D Knowledge Solar System route requires WebGL-capable hardware. Gesture
control additionally requires a browser permission grant and a compatible
camera, but camera frames are processed locally by the worker path.

Validation and privacy

• The two release screenshots contain no camera image or camera preview.
• The exporter opens SQLite read-only and writes generated output only to the
  requested directory.
• Generated graph exports may contain private summaries. Review them before
  sharing; do not commit live databases, transcripts, logs, tokens, cookies,
  or private paths.
• This release keeps fallback methods such as memory_save_fast, deterministic
  summaries, embedding fallbacks, and rag_fallback_index. Normal-path health
  does not mean those safety nets are removed.

One-sentence summary

v12.6.0 turns local agent memory into a navigable 2D/3D workspace while
making save, recall, graph expansion, and rules-layer boundaries easier to
trust and diagnose.