### Initialize MindVault Setup

Source: https://github.com/calebthecm/mindvault/blob/main/README.md

Runs the initial setup for MindVault. This can also be executed using the Python module.

```bash
mindvault setup                # or: python -m mindvault setup
```

--------------------------------

### Install MindVault with CLI

Source: https://github.com/calebthecm/mindvault/blob/main/README.md

Clones the MindVault repository, sets up a virtual environment, and installs MindVault with its dependencies, registering the CLI.

```bash
git clone https://github.com/calebthecm/MindVault
cd MindVault
python -m venv .venv && source .venv/bin/activate
pip install -e .
```

--------------------------------

### Install Ollama Models

Source: https://github.com/calebthecm/mindvault/blob/main/README.md

Installs the necessary Ollama models for vector search and chat/summarization. Ensure Ollama is running.

```bash
ollama pull nomic-embed-text   # vector search
ollama pull llama3.2           # chat and summarization
ollama serve                   # start Ollama if not running
```

--------------------------------

### MindVault Core Commands

Source: https://github.com/calebthecm/mindvault/blob/main/README.md

List of primary commands for interacting with MindVault, including chat, ingestion, and setup.

```bash
mindvault                           chat (default)
mindvault chat                      interactive REPL
mindvault chat --resume             resume last session
mindvault chat --resume <id>        resume specific session
mindvault ingest                    auto-discover and index all exports
mindvault ingest ./folder/          index a specific folder
mindvault ingest --force            re-index even if already processed
mindvault notes                     regenerate Obsidian notes
mindvault setup                     first-run configuration wizard
mindvault stats                     show index and session statistics
mindvault sessions                  list resumable sessions
mindvault consolidate               merge near-duplicate memories
```

--------------------------------

### Running MindVault via Pip

Source: https://github.com/calebthecm/mindvault/blob/main/README.md

Recommended method after installation. Execute MindVault and its subcommands directly from the terminal.

```bash
mindvault
mindvault chat
mindvault ingest
```

--------------------------------

### Install MindVault Dependencies

Source: https://github.com/calebthecm/mindvault/blob/main/README.md

Installs MindVault dependencies directly from the requirements file without registering the CLI.

```bash
pip install -r requirements.txt
```

--------------------------------

### Index and Chat with MindVault

Source: https://github.com/calebthecm/mindvault/blob/main/README.md

Commands to ingest all available data into MindVault and then start an interactive chat session with your indexed memory.

```bash
mindvault ingest               # index everything
mindvault chat                 # start talking to your brain
```

--------------------------------

### Running MindVault as a Python Module

Source: https://github.com/calebthecm/mindvault/blob/main/README.md

Alternative method that does not require installation. Use this to run MindVault directly from its source code.

```python
python -m mindvault
python -m mindvault chat
python -m mindvault ingest
```

--------------------------------

### Web Search Commands

Source: https://github.com/calebthecm/mindvault/blob/main/README.md

Initiate web searches using the /web command followed by your query. This feature uses DuckDuckGo for live search results.

```shell
/web what is the current price of ETH?
```

```shell
/web latest news on local SEO in 2025
```

--------------------------------

### MindVault JavaScript Initialization

Source: https://github.com/calebthecm/mindvault/blob/main/web/static/index.html

Initializes DOM element references and fetches server status upon page load.

```javascript
const messagesEl = document.getElementById('messages');
const form = document.getElementById('chat-form');
const input = document.getElementById('input');
const sendBtn = document.getElementById('send-btn');
const statusDot = document.getElementById('status-dot');
const modeSelect = document.getElementById('mode-select');
const emptyEl = document.getElementById('empty');

// Check server status
fetch('/api/status')
  .then(r => r.json())
  .then(d => {
    statusDot.className = 'ok';
    statusDot.title = `MindVault v${d.version} — connected`;
  })
  .catch(() => {
    statusDot.className = 'err';
    statusDot.title = 'Server unreachable';
  });
```

--------------------------------

### Configure Web Search Settings

Source: https://github.com/calebthecm/mindvault/blob/main/README.md

Customize web search behavior in config.py. Adjust the auto-search threshold and the maximum number of results to include in the context.

```python
WEB_SEARCH_AUTO_THRESHOLD = 0.45   # auto-search when best memory score is below this
```

```python
WEB_SEARCH_MAX_RESULTS    = 5      # results to include in context
```

--------------------------------

### Running MindVault via Legacy Script

Source: https://github.com/calebthecm/mindvault/blob/main/README.md

The original script-based execution method, still functional for running MindVault and its commands.

```python
python mindvault.py
python mindvault.py chat
python mindvault.py ingest
```

--------------------------------

### Render Source Chips

Source: https://github.com/calebthecm/mindvault/blob/main/web/static/index.html

Displays source information as clickable chips, showing title and score, and appends them to a container.

```javascript
function renderSources(container, sources = []) {
  const old = container.querySelector('.sources');
  if (old) old.remove();
  if (sources.length === 0) return;
  const chips = document.createElement('div');
  chips.className = 'sources';
  sources.forEach(s => {
    const chip = document.createElement('div');
    chip.className = 'source-chip';
    const label = s.title || s.chunk_id || 'source';
    chip.innerHTML = `${escapeHtml(label.slice(0, 28))}<span class="score">${s.score}</span>`;
    chip.title = label;
    chips.appendChild(chip);
  });
  container.appendChild(chips);
}
```

--------------------------------

### MindVault Link and Source Chip Styling

Source: https://github.com/calebthecm/mindvault/blob/main/web/static/index.html

Styles hyperlinks within messages and the 'source chip' elements used to display information sources.

```css
.bubble a {
  color: var(--blaze2);
  text-decoration: none;
}

.bubble a:hover {
  text-decoration: underline;
}

.sources {
  margin-top: 8px;
  display: flex;
  flex-wrap: wrap;
  gap: 6px;
}

.source-chip {
  font-size: 11px;
  padding: 2px 8px;
  border-radius: 99px;
  background: var(--border);
  color: var(--dim);
  white-space: nowrap;
  overflow: hidden;
  text-overflow: ellipsis;
  max-width: 220px;
}

.source-chip .score {
  color: var(--blaze2);
  margin-left: 4px;
}
```

--------------------------------

### Set Assistant Bubble Content and Render Sources

Source: https://github.com/calebthecm/mindvault/blob/main/web/static/index.html

Sets the content of a thinking bubble for an assistant's response and renders any associated sources. This is used when a successful answer is received from the server.

```javascript
setBubbleContent(thinkingBubble, 'assistant', answer);
renderSources(assistantMsg, payload.sources || []);
```

--------------------------------

### MindVault Body and Header Styling

Source: https://github.com/calebthecm/mindvault/blob/main/web/static/index.html

Styles the main body of the application, including background, font, and layout, and the header section with branding and status indicators.

```css
body {
  background: var(--ink);
  color: var(--text);
  font-family: "DM Sans", system-ui, sans-serif;
  height: 100dvh;
  display: flex;
  flex-direction: column;
}

header {
  display: flex;
  align-items: center;
  gap: 12px;
  padding: 14px 20px;
  border-bottom: 1px solid var(--border);
  background: var(--surface);
}

header h1 {
  font-size: 18px;
  font-weight: 700;
  letter-spacing: 0.12em;
  text-transform: uppercase;
  background: linear-gradient(90deg, var(--blaze), var(--blaze2));
  -webkit-background-clip: text;
  -webkit-text-fill-color: transparent;
}
```

--------------------------------

### MindVault Chat Session Commands

Source: https://github.com/calebthecm/mindvault/blob/main/README.md

Commands available during an active chat session for controlling reasoning, searching, note-taking, and managing the conversation.

```bash
Shift+Tab            cycle reasoning mode
/help                show all commands
/web <query>         search the web (DuckDuckGo, no API key needed)
/search <term>       search memory without LLM — shows scored results
/note <text>         quick-capture a note (indexed on next ingest)
/forget <topic>      suppress matching chunks from future retrieval
/mode [name]         show or switch mode (CHAT, PLAN, DECIDE, DEBATE, REFLECT, EXPLORE)
/sources             show which memories were used in the last answer
/remember <fact>     save a fact to this session
/private             toggle private vault inclusion
/resume              interactive session picker
/clear               clear conversation history
/quit, /exit         end session (compresses and saves automatically)
```

--------------------------------

### Render Full Markdown

Source: https://github.com/calebthecm/mindvault/blob/main/web/static/index.html

Parses markdown text, including code blocks, headings, lists, and paragraphs, into HTML using inline markdown rendering.

```javascript
function renderMarkdown(text) {
  const escaped = text.replace(/\r\n/g, '\n');
  const codeBlocks = [];
  const withBlocks = escaped.replace(/```(\w+)?\n([\s\S]*?)```/g, (_lang, lang, code) => {
    const block = `<pre><code>${escapeHtml(code.trim())}</code></pre>`;
    codeBlocks.push(block);
    return `@@CODEBLOCK_${codeBlocks.length - 1}@@`;
  });
  const paragraphs = withBlocks.split(/\n\s*\n/);
  const html = paragraphs.map(block => {
    const trimmed = block.trim();
    if (!trimmed) return '';
    if (/^@@CODEBLOCK_\d+@@$/.test(trimmed)) return trimmed;
    if (/^#{1,3}\s/.test(trimmed)) {
      const level = trimmed.match(/^#+/) [0].length;
      return `<h${level}>${renderInlineMarkdown(trimmed.replace(/^#{1,3}\s+/, ''))}</h${level}>
`;
    }
    if (trimmed.split('\n').every(line => /^\s*[-\*]\s+/.test(line))) {
      const items = trimmed.split('\n')
        .map(line => line.replace(/^\s*[-\*]\s+/, '').trim())
        .filter(Boolean)
        .map(line => `<li>${renderInlineMarkdown(line)}</li>`)
        .join('');
      return `<ul>${items}</ul>
`;
    }
    return `<p>${trimmed.split('\n').map(line => renderInlineMarkdown(line)).join('<br>')}</p>
`;
  }).join('');
  return html.replace(/@@CODEBLOCK_(\d+)@@/g, (_match, idx) => codeBlocks[Number(idx)]);
}
```

--------------------------------

### Submit Query and Stream Response

Source: https://github.com/calebthecm/mindvault/blob/main/web/static/index.html

Handles form submission, sends a query to the API, and streams the response back, updating the UI in real-time.

```javascript
form.addEventListener('submit', async e => {
  e.preventDefault();
  const query = input.value.trim();
  if (!query) return;
  input.value = '';
  input.style.height = 'auto';
  sendBtn.disabled = true;
  appendMessage('user', query);
  const { msg: assistantMsg, bubble: thinkingBubble } = appendMessage('assistant', '…');
  try {
    const res = await fetch('/api/chat/stream', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        query,
        mode: modeSelect.value,
        include_private: false,
      }),
    });
    if (!res.ok) {
      const err = await res.json().catch(() => ({ detail: res.statusText }));
      thinkingBubble.className = 'bubble';
      setBubbleContent(thinkingBubble, 'assistant', `Error: ${err.detail || 'request failed'}`);
      return;
    }
    const reader = res.body.getReader();
    const decoder = new TextDecoder();
    let buffer = '';
    let answer = '';
    while (true) {
      const { value, done } = await reader.read();
      if (done) break;
      buffer += decoder.decode(value, { stream: true });
      let boundary = buffer.indexOf('\n\n');
      while (boundary !== -1) {
        const rawEvent = buffer.slice(0, boundary);
        buffer = buffer.slice(boundary + 2);
        let eventName = 'message';
        let data = '';
        rawEvent.split('\n').forEach(line => {
          if (line.startsWith('event:')) eventName = line.slice(6).trim();
          if (line.startsWith('data:')) data += line.slice(5).trim();
        });
        if (eventName === 'token') {
          answer += JSON.parse(data);
          thinkingBubble.className = 'bubble';
          setBubbleContent(thinkingBubble, 'assistant', answer);
          messagesEl.scrollTop = messagesEl.scrollHeight;
        } else if (eventName === 'done') {
          const payload = JSON.parse(data);
          answer = payload.answer || answer;
          thinkingBubble.className = 'bubble';

```

--------------------------------

### MindVault Inline Code and Preformatted Text Styling

Source: https://github.com/calebthecm/mindvault/blob/main/web/static/index.html

Styles inline `<code>` elements and `<pre>` blocks for code snippets within messages, ensuring readability and distinct appearance.

```css
.bubble code {
  background: #171717;
  border: 1px solid #242424;
  border-radius: 6px;
  padding: 1px 5px;
  font-family: "SFMono-Regular", Consolas, monospace;
  font-size: 12px;
}

.bubble pre {
  background: #0d0d0d;
  border: 1px solid #242424;
  border-radius: 10px;
  padding: 12px;
  overflow-x: auto;
  margin: 8px 0;
}

.bubble pre code {
  background: transparent;
  border: none;
  padding: 0;
  font-size: 12px;
}
```

--------------------------------

### Render Inline Markdown

Source: https://github.com/calebthecm/mindvault/blob/main/web/static/index.html

Converts basic markdown syntax (code, links, bold, italics) within a string to HTML, after escaping HTML.

```javascript
function renderInlineMarkdown(text) {
  let html = escapeHtml(text);
  html = html.replace(/`([^`]+)`/g, '<code>$1</code>');
  html = html.replace(/\`\[([^\]]+)\]\((https?:\/\/[^\s]+)\)/g, '<a href="$2" target="_blank" rel="noreferrer">$1</a>');
  html = html.replace(/\*\*([^"]+)\*\*/g, '<strong>$1</strong>');
  html = html.replace(/\*([^
]+)\*/g, '<em>$1</em>');
  return html;
}
```

--------------------------------

### MindVault User and Assistant Bubble Colors

Source: https://github.com/calebthecm/mindvault/blob/main/web/static/index.html

Defines the distinct background colors and gradients for user-sent messages and assistant responses.

```css
.msg.user .bubble {
  background: linear-gradient(135deg, var(--blaze), var(--blaze2));
  color: #fff;
  border-bottom-right-radius: 3px;
}

.msg.assistant .bubble {
  background: var(--surface);
  border: 1px solid var(--border);
  color: var(--text);
  border-bottom-left-radius: 3px;
}

.msg.assistant .bubble.thinking {
  color: var(--dim);
  font-style: italic;
}
```

--------------------------------

### MindVault CSS Variables and Reset

Source: https://github.com/calebthecm/mindvault/blob/main/web/static/index.html

Defines CSS custom properties for color schemes and basic element resets for consistent styling across the application.

```css
*, *::before, *::after {
  box-sizing: border-box;
  margin: 0;
  padding: 0;
}

:root {
  --ink: #0a0a0a;
  --surface: #111111;
  --border: #1f1f1f;
  --dim: #6b7280;
  --text: #e5e7eb;
  --blaze: #ff6a00;
  --blaze2: #ff8a2a;
}
```

--------------------------------

### MindVault Bubble Spacing and Typography

Source: https://github.com/calebthecm/mindvault/blob/main/web/static/index.html

Controls spacing between paragraphs and lists within message bubbles, and styles headings and list items.

```css
.bubble p + p,
.bubble ul + p,
.bubble pre + p,
.bubble p + ul,
.bubble ul + ul,
.bubble pre + ul {
  margin-top: 10px;
}

.bubble h1,
.bubble h2,
.bubble h3 {
  font-size: 15px;
  margin: 12px 0 6px;
  color: #fff;
}

.bubble h1:first-child,
.bubble h2:first-child,
.bubble h3:first-child {
  margin-top: 0;
}

.bubble ul {
  padding-left: 18px;
  margin: 8px 0;
}

.bubble li + li {
  margin-top: 4px;
}
```

--------------------------------

### MindVault Mode Select Styling

Source: https://github.com/calebthecm/mindvault/blob/main/web/static/index.html

Styles the mode selection dropdown, including its appearance, focus states, and interactive elements.

```css
#mode-select {
  background: var(--border);
  color: var(--dim);
  border: 1px solid var(--border);
  border-radius: 6px;
  padding: 4px 8px;
  font-size: 12px;
  cursor: pointer;
}

#mode-select:focus {
  outline: none;
  border-color: var(--blaze);
  color: var(--text);
}
```

--------------------------------

### MindVault Form and Input Styling

Source: https://github.com/calebthecm/mindvault/blob/main/web/static/index.html

Styles the message input form, including the text area for user input and the send button.

```css
form {
  display: flex;
  gap: 10px;
  padding: 14px 20px;
  border-top: 1px solid var(--border);
  background: var(--surface);
}

#input {
  flex: 1;
  background: var(--ink);
  border: 1px solid var(--border);
  border-radius: 8px;
  color: var(--text);
  font-size: 14px;
  padding: 10px 14px;
  resize: none;
  min-height: 42px;
  max-height: 140px;
  font-family: inherit;
}

#input:focus {
  outline: none;
  border-color: var(--blaze);
}

#input::placeholder {
  color: var(--dim);
}

button[type=submit] {
  background: linear-gradient(135deg, var(--blaze), var(--blaze2));
  color: #fff;
  border: none;
  border-radius: 8px;
  padding: 10px 20px;
  font-size: 14px;
  font-weight: 600;
  cursor: pointer;
  white-space: nowrap;
  align-self: flex-end;
}

button[type=submit]:disabled {
  opacity: 0.5;
  cursor: not-allowed;
}
```

--------------------------------

### Handle Server Connection Errors

Source: https://github.com/calebthecm/mindvault/blob/main/web/static/index.html

Catches and displays errors that occur when attempting to reach the MindVault server. This is part of the error handling for network or server-side issues.

```javascript
thinkingBubble.className = 'bubble';
setBubbleContent(thinkingBubble, 'assistant', `Failed to reach MindVault server: ${err.message}`);
```

--------------------------------

### MindVault Status Dot Styling

Source: https://github.com/calebthecm/mindvault/blob/main/web/static/index.html

Styles the status indicator dot, including its default state and states for 'ok' (connected) and 'err' (unreachable).

```css
#status-dot {
  width: 8px;
  height: 8px;
  border-radius: 50%;
  background: #374151;
  margin-left: auto;
}

#status-dot.ok {
  background: #16a34a;
}

#status-dot.err {
  background: #dc2626;
}
```

--------------------------------

### MindVault Empty State Styling

Source: https://github.com/calebthecm/mindvault/blob/main/web/static/index.html

Styles the 'empty' state message displayed when there are no chat messages, including large, gradient-filled headings.

```css
#empty {
  margin: auto;
  text-align: center;
  color: var(--dim);
}

#empty h2 {
  font-size: 32px;
  font-weight: 800;
  letter-spacing: 0.1em;
  text-transform: uppercase;
  background: linear-gradient(90deg, var(--blaze), var(--blaze2));
  -webkit-background-clip: text;
  -webkit-text-fill-color: transparent;
  margin-bottom: 8px;
}

#empty p {
  font-size: 14px;
}
```

--------------------------------

### Submit Form on Enter Key

Source: https://github.com/calebthecm/mindvault/blob/main/web/static/index.html

Listens for the Enter key press on a textarea to submit the form, while allowing Shift+Enter for newlines.

```javascript
input.addEventListener('keydown', e => {
  if (e.key === 'Enter' && !e.shiftKey) {
    e.preventDefault();
    form.requestSubmit();
  }
});
```

--------------------------------

### MindVault Message Bubble Styling

Source: https://github.com/calebthecm/mindvault/blob/main/web/static/index.html

Styles individual message bubbles, including alignment for user and assistant messages, padding, and border-radius.

```css
.msg {
  max-width: 780px;
  width: 100%;
}

.msg.user {
  align-self: flex-end;
}

.msg.assistant {
  align-self: flex-start;
}

.bubble {
  padding: 12px 16px;
  border-radius: 12px;
  font-size: 14px;
  line-height: 1.6;
  word-break: break-word;
}
```

--------------------------------

### MindVault Messages Container Styling

Source: https://github.com/calebthecm/mindvault/blob/main/web/static/index.html

Styles the main chat messages area, enabling scrolling and defining layout for message elements.

```css
#messages {
  flex: 1;
  overflow-y: auto;
  padding: 20px;
  display: flex;
  flex-direction: column;
  gap: 16px;
}
```

--------------------------------

### Handle Error Response from MindVault Server

Source: https://github.com/calebthecm/mindvault/blob/main/web/static/index.html

Handles error events from the MindVault server by updating the thinking bubble with an error message. This snippet is used when the server returns an error.

```javascript
thinkingBubble.className = 'bubble';
setBubbleContent(thinkingBubble, 'assistant', `Error: ${JSON.parse(data)}`);
```

--------------------------------

### Finalize Message Sending and UI Update

Source: https://github.com/calebthecm/mindvault/blob/main/web/static/index.html

This code block executes in the finally clause, ensuring the send button is re-enabled, the input field is focused, and the message element is scrolled to the bottom, regardless of whether an error occurred.

```javascript
sendBtn.disabled = false;
input.focus();
messagesEl.scrollTop = messagesEl.scrollHeight;
```

--------------------------------

### Append Message to Chat

Source: https://github.com/calebthecm/mindvault/blob/main/web/static/index.html

Adds a new message (user or assistant) to the chat interface, including optional source information.

```javascript
function appendMessage(role, text, sources = []) {
  if (emptyEl) emptyEl.remove();
  const msg = document.createElement('div');
  msg.className = `msg ${role}`;
  const bubble = document.createElement('div');
  bubble.className = 'bubble' + (text === '…' ? ' thinking' : '');
  setBubbleContent(bubble, role, text);
  msg.appendChild(bubble);
  renderSources(msg, sources);
  messagesEl.appendChild(msg);
  messagesEl.scrollTop = messagesEl.scrollHeight;
  return { msg, bubble };
}
```

--------------------------------

### Set Chat Bubble Content

Source: https://github.com/calebthecm/mindvault/blob/main/web/static/index.html

Sets the inner HTML of a chat bubble, rendering markdown for assistant messages or plain text for user messages.

```javascript
function setBubbleContent(bubble, role, text) {
  if (role === 'assistant') {
    bubble.innerHTML = renderMarkdown(text);
  } else {
    bubble.textContent = text;
  }
}
```

--------------------------------

### Auto-resize Textarea

Source: https://github.com/calebthecm/mindvault/blob/main/web/static/index.html

Adjusts the height of a textarea element automatically based on its content, with a maximum height limit.

```javascript
input.addEventListener('input', () => {
  input.style.height = 'auto';
  input.style.height = Math.min(input.scrollHeight, 140) + 'px';
});
```

--------------------------------

### HTML Escaping Function

Source: https://github.com/calebthecm/mindvault/blob/main/web/static/index.html

Provides a utility function to escape HTML special characters, preventing XSS vulnerabilities.

```javascript
function escapeHtml(text) {
  return text
    .replace(/&/g, '&amp;')
    .replace(/</g, '&lt;')
    .replace(/>/g, '&gt;')
    .replace(/"/g, '&quot;')
    .replace(/'/g, '&#39;');
}
```

--------------------------------

### Disable Auto Web Search

Source: https://github.com/calebthecm/mindvault/blob/main/README.md

To disable automatic web searching, set the WEB_SEARCH_AUTO_THRESHOLD to 0 in config.py.

```python
WEB_SEARCH_AUTO_THRESHOLD = 0
```

--------------------------------

### Retrieval Scoring Formula

Source: https://github.com/calebthecm/mindvault/blob/main/README.md

The retrieval score is calculated using a weighted combination of embedding similarity, entity overlap, recency, and importance. This formula determines how relevant memories are.

```plaintext
score = 0.5 × embedding_similarity
      + 0.2 × entity_overlap
      + 0.2 × recency
      + 0.1 × importance
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.