Auto-tag notes · Summarise your week · Extract action items · Chat with your vault

---

⚡ Quick Start — up and running in 60 seconds

# 1️⃣  Build the plugin
npm install && npm run build

# 2️⃣  Install into your vault
mkdir -p <your-vault>/.obsidian/plugins/memex
cp main.js manifest.json styles.css <your-vault>/.obsidian/plugins/memex/

# 3️⃣  Enable in Obsidian
#     Settings → Community Plugins → Reload → Toggle "Memex" ON
#     Then set your AI provider (Local or Gemini) in Settings → Memex

Using Gemini? Grab a free API key from Google AI Studio — no local server needed.

Using a local LLM? Start LM Studio or Ollama and load a chat + embedding model.

---

🔒 Privacy & network use

Memex sends data only to the services you configure, and collects no telemetry.

Service	Used when	What is sent
Google Gemini API — if you choose the Gemini provider	Chatting, indexing, note commands	Your chat messages, the note excerpts retrieved as context, and, when indexing, the text of every note outside your excluded folders (to create embeddings). Auto-tag, Extract action items and Generate weekly summary send the notes they process. Covered by the Gemini API terms.
Local LLM server — LM Studio / Ollama, if you choose the local provider	Same as above	Sent to the endpoint you configure. The default is http://localhost:1234, so nothing leaves your machine.
Qdrant — optional, if you set Vector store to Qdrant	Indexing and searching	Note chunks and their embeddings, stored in the Qdrant instance you configure (local or Qdrant Cloud).

No account is required: Memex works fully with a local LLM server. Gemini needs a Google API key, and a shared index needs a Qdrant instance (Qdrant Cloud requires an account).

Stored inside your vault: chat history (.memex/conversations/), the search index (the plugin's folder), and your settings, including API keys in plain text in the plugin's data.json. Keep that in mind if you sync or share your vault.

---

✨ Features

💬 Chat with Your Vault

• Streaming responses — tokens appear in real-time as the LLM generates them, with automatic fallback to non-streaming if the server doesn't support it.
• Multiple conversations — create, rename, and delete chats; sidebar lists them sorted by last activity.
• Resizable sidebar — drag the divider or toggle the sidebar open/closed.
• Message actions (per-message ⋯ menu):
  • Copy any message to clipboard.
  • Edit & re-submit a user message (trims history and re-generates).
  • Regenerate an assistant response.
  • Delete a single message.
  • Export to note — saves a message as a new Markdown file in your vault.
• Per-conversation settings — override temperature, max tokens, system prompt, RAG top-K, and similarity threshold on a per-chat basis via the ⚙️ button.
• Personas — switch the assistant's personality (e.g., Zettelkasten Guide, Daily Reflector, Concise Summarizer). Fully customisable in settings.
• PDF export — right-click a chat in the sidebar → Export to PDF. Renders full Markdown with styled headings, code blocks, and lists into an A4 PDF saved to Memex/PDFs/.

🔎 RAG (Retrieval-Augmented Generation)

• Intelligent query rewriting — follow-up questions are automatically rewritten into standalone search queries using the LLM, so context isn't lost across turns.
• Content-hash indexing — only re-embeds notes whose content has actually changed; hashes are persisted to disk across reloads, eliminating redundant API calls.
• Deferred re-indexing — edited notes are queued and re-indexed when you switch to another note, not on every keystroke.
• Hybrid search — keyword (BM25) matching fused with semantic search via Reciprocal Rank Fusion, so exact names and terms are found as well as related ideas.
• Grounded answers — the assistant cites the notes it used, and says so when nothing in your vault is relevant enough, instead of answering from general knowledge.
• Optional shared index — keep the index in Qdrant (local or Qdrant Cloud) so every device uses the same one.
• Optimised vector store:
  • Float32Array embeddings with pre-computed norms for ~2–3× faster cosine similarity.
  • Min-heap top-K search — avoids sorting the entire index.
  • Path index for O(1) document lookups and deletions.
  • Compact JSON serialisation (~40% smaller on disk).
• Excluded folders — keep Templates, .obsidian, or any other folders out of the index.
• Manual & automatic — index the full vault on demand, or let the watcher handle it.

🏷️ Note Processing Commands

• Auto Tag Current Note — LLM suggests 3–5 relevant tags and prepends them.
• Extract Action Items — finds TODOs/tasks and appends them as a checklist.
• Generate Weekly Summary — summarises all notes modified in the last 7 days and saves the result to Weekly Summaries/{Year}/.

🔌 Modular AI Provider System

Swap between providers at any time — no restart required:

	Local (LM Studio / Ollama)	Google Gemini
Chat model	qwen/qwen3-vl-4b (default)	gemini-2.5-flash (default)
Embedding model	text-embedding-nomic-embed-text-v1.5	gemini-embedding-001
Server	Your local machine	Google Cloud (API key)

Both providers implement the same ILLMProvider / IEmbeddingProvider interfaces using OpenAI-compatible endpoints, so any model that speaks that protocol works.

🤖 MCP Server — your notes inside Claude

A standalone MCP server gives Claude Desktop, Claude Code and other MCP clients read-only access to your vault, using the plugin's own index and search.

• Tools — search_notes (hybrid semantic + keyword search with the same results as the chat panel; returns found: false when nothing clears the relevance threshold), read_note, list_notes. Each declares input and output JSON Schemas.
• Resources — every note as memex://note/{path} (Markdown), plus memex://index/stats (JSON).
• No extra config — reads the plugin's own settings (provider, API key, threshold, local or Qdrant index) from your vault.
• Read-only and sandboxed — never writes, and refuses paths outside the vault, including symlinks, hidden folders and your excluded folders.

Index your vault in Obsidian first, then build the server once:

npm run build:mcp   # → mcp-server.js

Claude Code:

claude mcp add memex --scope user -- node /absolute/path/to/memex/mcp-server.js "/absolute/path/to/your/vault"

Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "memex": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/memex/mcp-server.js", "/absolute/path/to/your/vault"]
    }
  }
}

Use the full path from which node: Claude Desktop doesn't see version managers such as nvm.

---

🎮 Usage

Commands

Open the Command Palette (Cmd/Ctrl + P) and search for Memex:

Command	Description
Open chat with journal	Opens the chat sidebar
Auto-tag current note	Analyses the note and prepends tags
Extract action items	Finds TODOs and appends a checklist
Generate weekly summary	Summarises the last 7 days of notes
Index vault for RAG	Full vault embedding index (with progress)
Clear RAG index	Wipes the index for a fresh rebuild
View RAG index statistics	Shows total indexed document chunks
Upload local index to Qdrant	Copies the existing index to Qdrant, reusing its embeddings
Debug RAG retrieval	Select text → shows the best-matching notes and their scores

Chat Interface

• Click the 💬 ribbon icon or run the Open chat with journal command.
• Type a message and press Enter (or Shift+Enter for a new line).
• Use the ⚙️ button next to Send to adjust per-chat settings.
• Right-click a conversation in the sidebar for rename / export / delete options.

---

⚙️ Settings

Go to Settings → Memex.

AI Provider

• Provider: Local (LM Studio / Ollama) or Google Gemini.

Local LLM Settings

• LLM Endpoint — URL of your local server (default http://localhost:1234).
• Chat Model — model identifier for chat completions.
• Embedding Model — model identifier for embeddings.

Google Gemini Settings

• API Key — your Gemini API key.
• Chat Model — Gemini model (default gemini-2.5-flash).
• Embedding Model — Gemini embedding model (default gemini-embedding-001).

General

• Weekly Summary Path — folder for weekly summaries.
• Default Temperature — controls randomness (0.0–1.0).
• Default Max Tokens — maximum response length.

RAG Settings

• Enable RAG — toggle retrieval features on/off.
• Chunk Size — words per chunk (default 200).
• Chunk Overlap — overlapping words between chunks (default 30).
• Top K Results — number of chunks to retrieve (default 6).
• Similarity Threshold — minimum relevance score (default 0.4).
• Auto-Index on Change — re-index notes on create/modify/delete.
• Excluded Folders — comma-separated list of folders to skip.

Personas

• Personas JSON — edit the array of {name, prompt} objects to customise assistant behaviour.

---

🏗️ Architecture

main.ts                  → Plugin entry point, commands, settings UI
├── settings.ts          → Settings type + defaults (shared with the MCP server)
├── providers.ts         → LLM & Embedding provider interfaces + Local/Gemini implementations
├── llm_service.ts       → LLM service (completion + streaming)
├── embedding_service.ts → Chunking + batch embedding generation
├── vector_store.ts      → IVectorStore + local JSON store (Float32Array + min-heap search)
├── qdrant_store.ts      → Qdrant-backed store (plain REST), shared across devices
├── lexical_index.ts     → BM25 keyword index + Reciprocal Rank Fusion for hybrid search
├── rag_service.ts       → RAG orchestration (indexing, retrieval, query rewriting)
├── processor.ts         → Note processing (tags, action items, weekly summary)
├── conversation_manager.ts → Conversation CRUD (JSON files in .memex/)
└── chat_view.ts         → Chat UI (sidebar, messages, streaming, PDF export)

mcp/server.ts            → MCP server (stdio) reusing the retrieval code above

---

🗺️ Roadmap

• Multi-modal notes — image and PDF understanding via vision models
• Graph-aware RAG — leverage Obsidian's link graph to boost retrieval relevance
• Ollama auto-detect — automatically discover running models, no manual config
• Mobile support — optimise the chat UI and indexing for Obsidian Mobile
• Semantic search command — vault-wide natural language search from the command palette
• Note generation — create new notes from chat responses with backlinks
• Scheduled summaries — automatic daily/weekly/monthly summaries on a cron
• Plugin marketplace — submit to the Obsidian Community Plugins directory

Have an idea? Open an issue — PRs welcome!

---

🤝 Contributing

Contributions are welcome — whether it's a bug fix, new feature, or documentation improvement.

1. Fork the repo and create a new branch:

   git checkout -b feature/my-feature

2. Make your changes — follow the existing code style and add comments where needed.
3. Build & test to make sure everything compiles:

   npm run build

4. Submit a Pull Request with a clear description of what you changed and why.

Development Setup

git clone https://github.com/manas-33/memex.git
cd memex
npm install
npm run dev    # Watch mode — rebuilds on file changes

Then symlink or copy the built files into your vault's .obsidian/plugins/memex/ folder and reload Obsidian.

---

📄 License

MIT — see LICENSE for details.