Client-Side Spatial Learning & Memory Palace Architecture: In-Browser Semantic Vector Retrieval and Multi-Provider LLM Orchestration

1. Abstract & Architectural Vision

Modern educational software and AI study companions routinely compromise user privacy by transmitting personal study materials, lecture transcripts, and sensitive research documents to remote cloud infrastructure for vector indexing and LLM prompt completion. Furthermore, server-bound Retrieval-Augmented Generation (RAG) architectures incur recurrent API database costs, network latency penalties, and complete failure modes during offline or low-connectivity scenarios.

VibeLocus introduces a paradigm shift: a comprehensive spatial learning, AI tutoring, and memory palace indexing framework executing 100% client-side inside standard modern web browsers. Published as the vibelocus open-source NPM library and companion Next.js application, the system processes multi-format raw documents (PDF, DOCX, TXT, Markdown), generates hierarchical syllabi, performs in-browser semantic vector retrieval, and persists knowledge into an organized Memory Palace database in IndexedDB without a single byte of private telemetry ever leaving the user's machine.

2. In-Browser Semantic Vector Retrieval (WASM & WebGPU)

Traditional RAG pipelines rely on external managed vector databases (such as Pinecone, Qdrant, or Weaviate). VibeLocus eliminates cloud vector databases by executing the all-MiniLM-L6-v2 transformer model directly within client memory via WebAssembly and WebGPU execution pipelines.

When a study document or topic is imported, text is partitioned into semantically coherent chunks and passed through the local transformer:

// Cosine similarity between query vector Q and stored drawer vector D
sim(Q, D) = (Q · D) / (||Q|| * ||D||)

where:
  Q = 384-dimensional query embedding vector
  D = 384-dimensional indexed document chunk vector
  ||V|| = sqrt(sum(V_i^2)) for i in [0..383]

Because vectors reside in typed Float32Array buffers within IndexedDB, cosine similarity searches across thousands of indexed concepts execute in sub-4 milliseconds directly in JavaScript, providing instantaneous semantic search across the student's entire knowledge repository.

3. Hierarchical Spatial Memory Palace (IndexedDB Engine)

To enhance cognitive retention and mirror classical mnemonic techniques, VibeLocus organizes stored knowledge using a three-tier spatial hierarchy:

• Wings: Macro-level academic domains (e.g., Computer Science, Neurobiology, Quantum Physics).
• Rooms: Intermediate topic clusters (e.g., Algorithms, Synaptic Transmission, Wave Mechanics).
• Drawers: Granular atomic concept cards holding compressed content, raw sizes, timestamps, and semantic embeddings.

By pairing IndexedDB with lossless LZString data compression, VibeLocus reduces storage footprint by over 60%, allowing students to store thousands of textbooks and research papers while staying well within standard browser storage quotas (tracked in real-time via navigator.storage.estimate()).

4. Multi-Provider Client-Side LLM Orchestration

The core tutoring intelligence is powered by a modular, unified orchestration hook (useLLM) that abstracts disparate inference backends into a uniform chat and syllabus generation interface:

1. Google Gemini: Direct REST invocation using Gemini 1.5 Pro / Flash with structured JSON schema output.
2. OpenAI: Direct streaming completions via GPT-4o / GPT-4o-mini.
3. Localhost Ollama: Zero-cloud inference routing to local hardware models (Llama 3, Mistral, Phi-3) via http://localhost:11434.
4. Chrome Built-in AI: Direct native inference utilizing Google Chrome's internal Gemini Nano through window.ai.
5. In-Browser WebAssembly: Local model execution using HuggingFace Transformers.js without any network requests.

5. Client-Side Security & Safe Markdown Tokenization

Because educational content generated by AI or uploaded via untrusted files frequently contains raw markdown and HTML entities, standard rendering via dangerouslySetInnerHTML exposes web applications to cross-site scripting (XSS) attacks.

VibeLocus implements a custom Abstract Syntax Tree (AST) markdown tokenizer (SafeMarkdown) that recursively builds React virtual DOM nodes without invoking native browser HTML innerHTML parsers:

Raw Input String 
  ──> Tokenizer (Headers, Lists, Code, Math) 
  ──> Sanitizer (Strip script, iframe, onload handlers) 
  ──> React Virtual DOM Hierarchy (Zero innerHTML execution)

6. Open-Source NPM Package Documentation: vibelocus

Developers building educational platforms, AI tutors, or knowledge management tools can install the full VibeLocus SDK directly from NPM:

npm install vibelocus react react-dom

Quickstart: Multi-Provider AI Tutoring Hook (`useLLM`)

The useLLM hook provides instant access to client-side tutoring prompts across any configured provider:

import React, { useState } from "react";
import { useLLM } from "vibelocus/hooks";
import { SafeMarkdown } from "vibelocus/components";

export function AssistantComponent() {
  const { queryLLM, apiProvider, setApiProvider } = useLLM();
  const [response, setResponse] = useState<string>("");

  const handleQuery = async () => {
    const messages = [
      { role: "user", content: "Explain quantum superposition and entanglement in simple terms." }
    ];
    const result = await queryLLM(messages, "You are a concise academic tutor.");
    setResponse(result);
  };

  return (
    <div className="tutor-container">
      <button onClick={handleQuery}>Ask Question</button>
      <SafeMarkdown content={response} />
    </div>
  );
}

Quickstart: Spatial Memory Palace Storage (`useIndexedDB`)

import React from "react";
import { useIndexedDB } from "vibelocus/hooks";

export function MemoryComponent() {
  const { drawers, stats, quota, addDrawer } = useIndexedDB();

  const handleSaveConcept = async () => {
    await addDrawer({
      wing: "Computer Science",
      room: "Algorithms",
      drawer: "Graph Traversal",
      compressedContent: "Breadth-First Search utilizes FIFO queue semantics...",
      embedding: null,
      rawSize: 140,
      compressedSize: 52,
      createdAt: Date.now()
    });
  };

  return (
    <div>
      <button onClick={handleSaveConcept}>Save to Memory Palace</button>
      <p>Total Drawers: {stats.drawersCount}</p>
      <p>Storage Quota: {quota.usage} / {quota.quota} bytes</p>
    </div>
  );
}

7. Conclusion & Future Roadmap

VibeLocus demonstrates that private, state-of-the-art AI learning environments can be delivered directly inside standard browsers without reliance on centralized server databases. Ongoing research includes integrating WebGPU-accelerated 3D memory palace visualization canvases, spatial VR navigation via WebXR, and peer-to-peer WebRTC syllabus synchronization.

Dibyajyoti Rout

Founder & Systems Architect, Animatrous Engineering Lab. Author of vibelocus, handforge, nexadesk, @animatrous/shadow-boxer, and void-runner.