mirror of
https://github.com/khodges42/glassMind.git
synced 2026-06-14 18:18:36 +00:00
536 lines
9.2 KiB
Markdown
536 lines
9.2 KiB
Markdown
````md
|
|
# FAQ.md
|
|
|
|
# Frequently Asked Questions
|
|
|
|
## What is Glassmind?
|
|
|
|
Glassmind is a local-first semantic retrieval and memory system for markdown knowledge bases.
|
|
|
|
It indexes markdown files, builds semantic and structural search indexes, and exposes retrieval APIs for:
|
|
- AI assistants
|
|
- local models
|
|
- agents
|
|
- MCP clients
|
|
- automation tooling
|
|
- humans using the CLI directly
|
|
|
|
Glassmind is designed to work especially well with Obsidian vaults, but only requires a directory of markdown files.
|
|
|
|
---
|
|
|
|
# What problem is Glassmind solving?
|
|
|
|
Modern LLMs are powerful but stateless.
|
|
|
|
They:
|
|
- lose context
|
|
- forget projects
|
|
- cannot inherently understand your local files
|
|
- have limited prompt windows
|
|
- hallucinate when context is missing
|
|
|
|
Meanwhile many people already maintain:
|
|
- engineering documentation
|
|
- project journals
|
|
- research notes
|
|
- worldbuilding
|
|
- task tracking
|
|
- personal knowledge systems
|
|
|
|
inside markdown repositories.
|
|
|
|
Glassmind bridges those worlds.
|
|
|
|
It provides:
|
|
- retrieval
|
|
- semantic search
|
|
- context construction
|
|
- memory indexing
|
|
|
|
over existing markdown workflows.
|
|
|
|
---
|
|
|
|
# Is Glassmind an AI agent?
|
|
|
|
No.
|
|
|
|
Glassmind is retrieval infrastructure.
|
|
|
|
It does not:
|
|
- autonomously execute tasks
|
|
- reason independently
|
|
- act as a chatbot
|
|
- replace orchestration frameworks
|
|
|
|
It is closer to:
|
|
- a search engine
|
|
- a semantic index
|
|
- a memory API
|
|
- a retrieval layer
|
|
|
|
Agents and AI tools call Glassmind to retrieve relevant context.
|
|
|
|
---
|
|
|
|
# Is Glassmind tied to Obsidian?
|
|
|
|
No.
|
|
|
|
Glassmind is markdown-native.
|
|
|
|
It works with:
|
|
- Obsidian vaults
|
|
- plain markdown directories
|
|
- docs repositories
|
|
- PKM systems
|
|
- engineering notebooks
|
|
- wiki-style folder structures
|
|
|
|
Obsidian is simply a particularly good fit because:
|
|
- it is local-first
|
|
- it uses markdown
|
|
- it has strong linking semantics
|
|
- it is widely adopted
|
|
|
|
Glassmind treats markdown files as canonical regardless of editor.
|
|
|
|
---
|
|
|
|
# Why markdown?
|
|
|
|
Because markdown is:
|
|
- portable
|
|
- durable
|
|
- inspectable
|
|
- editor-agnostic
|
|
- version-control friendly
|
|
- human-readable
|
|
|
|
Glassmind intentionally avoids proprietary storage formats for primary knowledge.
|
|
|
|
The markdown files remain the source of truth.
|
|
|
|
Everything else is rebuildable.
|
|
|
|
---
|
|
|
|
# What is the source of truth?
|
|
|
|
The markdown files.
|
|
|
|
Glassmind builds:
|
|
- indexes
|
|
- caches
|
|
- embeddings
|
|
- retrieval metadata
|
|
|
|
on top of them.
|
|
|
|
The database is disposable and rebuildable.
|
|
|
|
If Glassmind disappears, the notes still work.
|
|
|
|
---
|
|
|
|
# What database does Glassmind use?
|
|
|
|
Planned v1:
|
|
|
|
```text
|
|
SQLite
|
|
sqlite-vec
|
|
```
|
|
|
|
SQLite stores:
|
|
- note metadata
|
|
- chunk metadata
|
|
- tags
|
|
- links
|
|
- retrieval state
|
|
- indexes
|
|
|
|
sqlite-vec stores:
|
|
- semantic vectors ("embeddings")
|
|
|
|
The database is local and rebuildable.
|
|
|
|
---
|
|
|
|
# Why SQLite?
|
|
|
|
Because SQLite is:
|
|
- local-first
|
|
- fast enough
|
|
- battle-tested
|
|
- portable
|
|
- operationally simple
|
|
|
|
Glassmind intentionally avoids requiring:
|
|
- external database servers
|
|
- cloud infrastructure
|
|
- distributed systems
|
|
- operational overhead
|
|
|
|
for normal usage.
|
|
|
|
---
|
|
|
|
# What are embeddings?
|
|
|
|
Embeddings are vector representations of semantic meaning.
|
|
|
|
A chunk of text is transformed into a vector like:
|
|
|
|
```text
|
|
[0.12, -0.44, 0.89, ...]
|
|
```
|
|
|
|
Vectors with similar meaning are located near each other mathematically.
|
|
|
|
This enables semantic search.
|
|
|
|
Example:
|
|
|
|
```text
|
|
"persistent semantic cache"
|
|
```
|
|
|
|
can match:
|
|
|
|
```text
|
|
"local memory system"
|
|
```
|
|
|
|
even if the wording differs.
|
|
|
|
---
|
|
|
|
# Does Glassmind require online APIs?
|
|
|
|
No.
|
|
|
|
Glassmind is designed for local operation.
|
|
|
|
Planned local embedding options:
|
|
- Ollama
|
|
- fastembed-rs
|
|
- llama.cpp-compatible backends
|
|
|
|
Cloud embeddings may eventually be optional, but local-first is the default philosophy.
|
|
|
|
---
|
|
|
|
# What is hybrid retrieval?
|
|
|
|
Glassmind does not rely solely on embeddings.
|
|
|
|
Retrieval combines:
|
|
- semantic similarity
|
|
- keyword matching
|
|
- tags
|
|
- wikilinks
|
|
- recency
|
|
- project/path weighting
|
|
- hot memory boosting
|
|
|
|
This generally performs better than pure vector search.
|
|
|
|
---
|
|
|
|
# What is a chunk?
|
|
|
|
A chunk is a retrieval unit.
|
|
|
|
Instead of embedding entire files, Glassmind splits documents into smaller pieces.
|
|
|
|
Usually:
|
|
- heading sections
|
|
- paragraphs
|
|
- task blocks
|
|
- code blocks
|
|
- fixed-size fallback windows
|
|
|
|
Chunking improves:
|
|
- retrieval quality
|
|
- precision
|
|
- context density
|
|
- token efficiency
|
|
|
|
---
|
|
|
|
# What is a context bundle?
|
|
|
|
A context bundle is an LLM-ready retrieval result.
|
|
|
|
Instead of returning raw search matches only, Glassmind can assemble:
|
|
- relevant chunks
|
|
- related notes
|
|
- recent project activity
|
|
- linked concepts
|
|
- source references
|
|
|
|
into a structured payload optimized for AI consumption.
|
|
|
|
Example:
|
|
|
|
```text
|
|
"Help me continue the Glassmind architecture work"
|
|
```
|
|
|
|
might retrieve:
|
|
- recent architecture notes
|
|
- TODOs
|
|
- design decisions
|
|
- linked experiments
|
|
- related discussions
|
|
|
|
within a configurable token budget.
|
|
|
|
---
|
|
|
|
# What is MCP?
|
|
|
|
MCP stands for:
|
|
|
|
```text
|
|
Model Context Protocol
|
|
```
|
|
|
|
It is a protocol used by AI tools to interact with external systems and tools.
|
|
|
|
Glassmind plans to expose MCP-compatible retrieval tools such as:
|
|
|
|
```text
|
|
glassmind_search
|
|
glassmind_context
|
|
glassmind_read
|
|
```
|
|
|
|
This allows tools like Claude Code or other agent systems to retrieve vault context directly.
|
|
|
|
---
|
|
|
|
# How is Glassmind different from traditional RAG systems?
|
|
|
|
Many RAG systems are:
|
|
- cloud-first
|
|
- opaque
|
|
- tightly coupled to vector databases
|
|
- detached from user workflows
|
|
- document-ingestion pipelines rather than knowledge systems
|
|
|
|
Glassmind is designed around:
|
|
- local-first operation
|
|
- markdown-native workflows
|
|
- inspectability
|
|
- rebuildability
|
|
- human-readable source material
|
|
- AI + human co-usage
|
|
|
|
Glassmind assumes the markdown corpus is already meaningful.
|
|
|
|
It focuses on retrieval quality and continuity.
|
|
|
|
---
|
|
|
|
# How is Glassmind different from vector databases?
|
|
|
|
Vector databases store embeddings and perform nearest-neighbor search.
|
|
|
|
Glassmind is:
|
|
- retrieval orchestration
|
|
- indexing
|
|
- chunking
|
|
- metadata extraction
|
|
- semantic ranking
|
|
- context assembly
|
|
- markdown-aware infrastructure
|
|
|
|
Glassmind may use vector storage internally, but it is not merely a vector DB wrapper.
|
|
|
|
---
|
|
|
|
# Will Glassmind modify my notes?
|
|
|
|
By default:
|
|
- no direct user note modification
|
|
|
|
Glassmind may optionally write to:
|
|
|
|
```text
|
|
.agent/
|
|
```
|
|
|
|
for:
|
|
- summaries
|
|
- logs
|
|
- generated memory
|
|
- task state
|
|
- context artifacts
|
|
|
|
Future configurable modes may support:
|
|
- proposed diffs
|
|
- explicit approvals
|
|
- direct modification
|
|
|
|
but user ownership and safety are priorities.
|
|
|
|
---
|
|
|
|
# Why not just use grep or ripgrep?
|
|
|
|
Keyword search is extremely useful and Glassmind still supports it.
|
|
|
|
But semantic retrieval solves problems like:
|
|
|
|
```text
|
|
"I know I wrote about this concept but I forgot the terminology."
|
|
```
|
|
|
|
Glassmind combines:
|
|
- keyword retrieval
|
|
- semantic retrieval
|
|
- structural metadata
|
|
- recency
|
|
- graph relationships
|
|
|
|
rather than replacing traditional search entirely.
|
|
|
|
---
|
|
|
|
# Why not use a graph database?
|
|
|
|
Maybe eventually.
|
|
|
|
But for v1:
|
|
- simplicity
|
|
- rebuildability
|
|
- portability
|
|
- operational sanity
|
|
|
|
matter more.
|
|
|
|
SQLite plus semantic indexing is likely sufficient for:
|
|
- personal vaults
|
|
- power-user vaults
|
|
- local AI workflows
|
|
|
|
Graph semantics can still exist logically without introducing a distributed graph infrastructure problem on day one.
|
|
|
|
---
|
|
|
|
# Is Glassmind intended for teams?
|
|
|
|
Not initially.
|
|
|
|
The primary target is:
|
|
- individuals
|
|
- researchers
|
|
- engineers
|
|
- writers
|
|
- local AI workflows
|
|
- personal knowledge systems
|
|
|
|
Future multi-user support is possible but not the immediate focus.
|
|
|
|
---
|
|
|
|
# What does “local-first” actually mean here?
|
|
|
|
The intended default behavior is:
|
|
|
|
- local storage
|
|
- localhost-only networking
|
|
- optional offline operation
|
|
- local embeddings
|
|
- markdown canonical storage
|
|
- rebuildable indexes
|
|
- no required cloud dependency
|
|
- no telemetry
|
|
|
|
Glassmind should remain usable:
|
|
- disconnected
|
|
- self-hosted
|
|
- archived
|
|
- years into the future
|
|
|
|
---
|
|
|
|
# What does “hot memory” mean?
|
|
|
|
Glassmind conceptually separates retrieval into:
|
|
- hot memory
|
|
- warm memory
|
|
- cold memory
|
|
|
|
Hot memory includes:
|
|
- recent notes
|
|
- active projects
|
|
- pinned information
|
|
- recently retrieved context
|
|
|
|
Cold memory still exists, but is less likely to be automatically surfaced.
|
|
|
|
This helps context selection remain relevant without deleting historical information.
|
|
|
|
---
|
|
|
|
# What are the long-term goals?
|
|
|
|
Long-term goals include:
|
|
- strong retrieval quality
|
|
- excellent local AI workflows
|
|
- durable markdown-native memory infrastructure
|
|
- robust MCP integration
|
|
- context continuity across sessions
|
|
- transparent retrieval behavior
|
|
- inspectable ranking systems
|
|
- ergonomic semantic search
|
|
|
|
Not:
|
|
- replacing human thought
|
|
- building autonomous AGI office workers
|
|
- trapping users inside proprietary ecosystems
|
|
|
|
---
|
|
|
|
# Why is the project opinionated?
|
|
|
|
Because retrieval quality and long-term maintainability depend heavily on architecture choices.
|
|
|
|
Glassmind intentionally prefers:
|
|
- explicit systems
|
|
- rebuildable state
|
|
- inspectability
|
|
- portability
|
|
- user ownership
|
|
- operational simplicity
|
|
|
|
over:
|
|
- hidden magic
|
|
- giant opaque pipelines
|
|
- cloud dependence
|
|
- maximal abstraction
|
|
|
|
---
|
|
|
|
# Why the name “Glassmind”?
|
|
|
|
The original idea was:
|
|
|
|
```text
|
|
semantic transparency into your own thoughts
|
|
```
|
|
|
|
The system is supposed to feel like:
|
|
- peering through glass
|
|
- inspecting memory
|
|
- traversing thought structures
|
|
|
|
rather than interacting with a black box.
|
|
|
|
Also it sounded less alarming than some of the other candidate names.
|
|
````
|