Sahara

Extended storage, searchable memory and instant retrieval.

Sahara turns folders on your computer into searchable memory. Find files by meaning, ask questions with cited sources, and expose the same local index to MCP clients. External drives, MinIO, and AWS storage are optional extensions, not prerequisites.

Local-first: indexing and semantic search run on your computer. No account, API key, storage bucket, or additional drive is required for the core search experience.

Latest release: v0.3.0 adds a signed, notarized native macOS installer, guided first-run onboarding, and opt-in MCP memory capture. A Windows (x64) installer and a Linux x86_64 portable archive build successfully but aren't signed/published yet (#106, #48). See the changelog.

_{Fictional documents shown in a generic MCP client. Sahara retrieves from the configured local index, cites its sources, and reports when a requested detail is absent.}

What Sahara Does

• Searches PDFs, DOCX files, EPUB ebooks, notes, code, and other text documents by meaning
• Answers questions over indexed files with source paths and supporting snippets
• Indexes multiple folders without copying them to a storage backend
• Exposes read-only search and Q&A tools through MCP, plus an opt-in tool that lets an MCP client (like Claude Desktop) save something to Sahara memory when you explicitly ask it to
• Optionally syncs selected folders to a drive, NAS, MinIO, or AWS S3
• Can offload verified stored files while keeping their indexed content searchable

Sahara is a single-user CLI and local retrieval service. It is not a hosted cloud service, autonomous agent, or general filesystem access layer.

Quick Start

Native app — no Python required

A signed, notarized installer is available for macOS on Apple Silicon (M1/M2/M3/M4) — no Git, Python, pip, or pipx needed. This does not run on Intel Macs; if you have an Intel Mac, use CLI via pipx below instead.

1. Download the installer: sahara-0.3.0-macos-arm64.pkg (the release page also lists a .sha256 checksum and a manifest file — you can ignore both, they're for verification, not installation).
2. Open Terminal and go to the folder you downloaded it to (usually Downloads):

   cd ~/Downloads

3. Install it:

   sudo installer -pkg sahara-0.3.0-macos-arm64.pkg -target /

   This asks for your Mac login password (for sudo), not a separate Sahara password.
4. Confirm it installed:

   sahara --version

5. A new Terminal window opens automatically a few seconds after step 3 and walks you through first-run setup: choosing folders to index, building the first index, keeping it automatically current, and optionally connecting Claude Desktop — including whether to let Claude save things to Sahara memory, off by default. If it doesn't open on its own, run sahara-first-run yourself.

A Windows (x64) installer and a Linux x86_64 portable archive build successfully from source today but aren't signed and published yet — see Installation for exact steps per platform, including building those yourself in the meantime.

CLI via pipx

Sahara requires Python 3.11 or newer.

The Python distribution is named sahara-memory, but it installs the sahara command. Do not run pip install sahara; that name belongs to the unrelated OpenStack project.

Install Sahara from PyPI with pipx, which keeps CLI applications isolated from the system Python:

pipx install "sahara-memory[search,mcp]"

sahara setup --folder ~/Documents
sahara search "my tax return from 2024" --snippet

Or run the steps individually:

pipx install "sahara-memory[search,mcp]"

sahara init --mode basic --folder ~/Documents
sahara index
sahara search "my tax return from 2024" --snippet

See Installation for native installers, Linux portable archives, package-manager paths, pipx setup, a virtual environment alternative, and the externally-managed-environment fix. Do not use --break-system-packages.

The first sahara index downloads a local embedding model of roughly 70 MB. Hugging Face may show an unauthenticated-download warning; no account or token is required.

Add more folders whenever you need them:

sahara folder add ~/Projects
sahara index

Every folder added this way remains index-only unless you explicitly enable storage sync for it.

Ask Questions

sahara ask is retrieval-only by default. It returns ranked source snippets without contacting Ollama, OpenAI, or another standalone answer model:

sahara ask --snippet "what does the lease say about pets?"

An MCP client can reason over the same retrieved evidence with its own model. Enable a separate answer provider only when you want the Sahara CLI or MCP tool to generate the answer itself.

Optional local answers with Ollama

Install Ollama, then download Sahara's default model:

ollama pull mistral
sahara config set answer_provider ollama
sahara ask --snippet "what does the lease say about pets?"

The current Mistral download is approximately 4.4 GB. If Ollama is not already running, launch the application or run ollama serve in another terminal.

OpenAI without Ollama

Ollama is not required when you prefer OpenAI:

export OPENAI_API_KEY="your-api-key"
sahara config set answer_provider openai
sahara ask --snippet "what does the lease say about pets?"

Windows PowerShell:

$env:OPENAI_API_KEY = "your-api-key"
sahara config set answer_provider openai
sahara ask --snippet "what does the lease say about pets?"

Sahara stores the provider preference, not the API key. When OpenAI is selected, the question and retrieved snippets needed to answer it are sent to OpenAI. OpenAI API billing is separate from a ChatGPT subscription.

See Answer Provider Setup for installation, model selection, privacy details, and troubleshooting.

Capture Knowledge

Save something you learned as a durable Markdown memory:

sahara remember "Vendor X uses net-30 terms" \
  --source conversation \
  --tag vendor

cat meeting-notes.txt | sahara remember --source conversation

sahara recall "Which vendor uses net-30?" --tag vendor
sahara memory list --source conversation

Sahara creates a managed ~/Sahara Memory content root on first capture, keeps storage sync disabled until you explicitly enable it, and indexes only the new note. If the embedding model is unavailable, the Markdown file is still saved and can be indexed later with sahara index.

Use sahara memory show, edit, and delete with a memory UUID or exact title. sahara memory rebuild reconstructs the catalog and search state from the Markdown files, which remain the source of truth.

The broader recall, MCP, mobile, and Siri rollout is described in the captured knowledge plan. The companion-app evaluation and rollout recommendation live in the mobile companion app spike.

Connect an MCP Client

Sahara exposes six read-only MCP tools for search, cited Q&A, chunk reads, folder listing, index status, and captured-memory recall. These tools operate only on Sahara's indexed corpus; they cannot browse arbitrary files or modify your data.

No standalone Sahara answer provider is required; the MCP client can use Sahara's retrieved snippets directly. Claude Desktop is the first tested client:

sahara mcp install-claude

To let Claude save a memory only when you explicitly ask it to, opt in locally:

sahara mcp install-claude --enable-memory-write

The native app's guided sahara-first-run asks this as a yes/no question when it connects Claude Desktop, instead of requiring you to know this flag exists.

This adds the create-only sahara_remember tool. It is unavailable over HTTP/SSE and cannot edit, delete, sync, browse arbitrary paths, or run shell commands.

Fully quit and reopen Claude Desktop, then confirm sahara appears under Connectors. The installer preserves existing settings and MCP servers, uses Sahara's absolute executable path, and creates a backup before changing an existing config.

See Claude Desktop Setup for verification and troubleshooting, or MCP Integrations for the tool surface and authenticated remote transport.

Optional Storage

Start with local indexing. Add storage later without rebuilding the semantic index.

Setup	What it provides	Status
Basic	Local indexing across one or more folders	Core mode
Local drive	Copies selected folders to an external drive, NAS, or network share	Optional
AWS	Copies selected folders to S3, with optional Glacier features	Optional

Attach a local drive:

sahara storage configure local --drive /Volumes/Archive/Sahara
sahara folder sync ~/Documents --enable
sahara sync

Attach AWS:

sahara storage configure aws \
  --bucket my-sahara-bucket \
  --region us-east-1
sahara folder sync ~/Documents --enable
sahara sync

MinIO and local-plus-Glacier modes are available through the interactive sahara init wizard. See Getting Started for storage credentials, content-root behavior, deletion semantics, and migration paths.

After a file has been synced and indexed, Sahara can free its source disk space while retaining search metadata:

sahara offload Documents/archive/report.pdf
sahara fetch Documents/archive/report.pdf

Offload verifies the stored copy before removing the local source. Ordinary filesystem deletion is not treated as offload.

Privacy and Security

• The semantic index is stored locally in ~/.sahara/state.db.
• Indexing, embeddings, and sahara search stay local.
• Ollama answer generation stays local when explicitly enabled.
• OpenAI receives the question and retrieved snippets when explicitly selected.
• MCP is read-only by default and scoped to indexed content.
• Optional MCP memory capture is create-only, local-stdio-only, explicitly enabled, size-limited, idempotent, and audited without storing captured text in the audit log.
• Remote MCP requires authentication by default and supports tool, folder, and snippet limits.
• Optional storage encryption uses client-side AES-256-GCM.

Review SECURITY.md before exposing MCP remotely or relying on encrypted storage.

Supported Content

Sahara extracts text from:

• PDF, DOCX, and EPUB documents
• Markdown, reStructuredText, and plain text
• Python, JavaScript, TypeScript, JSON, YAML, TOML, CSV, HTML, and XML
• Other files that can be safely detected as UTF-8 text

Current limitations:

• Scanned PDFs and images are not searchable because OCR is not implemented yet.
• Audio and video transcription are not supported.
• Sahara is designed for one user and one local index.
• The project is beta; keep independent backups of important files.

Use sahara index-report to inspect indexed files, unsupported content, and failures.

Create a .saharaignore file in any indexed folder to exclude content using gitignore-style patterns:

.env*
secrets/
node_modules/
*.tmp

Start from the example ignore file for common operating-system, editor, build, and credential exclusions.

Each content root manages its own .saharaignore independently. sahara init creates one in the primary folder, and sahara folder add PATH creates one in every additional root you add (without overwriting a .saharaignore that already exists there).

Core Commands

Command	Purpose
sahara init --mode basic --folder PATH	Create an index-only local library
sahara folder add/list/remove	Manage indexed folders
sahara index [--force]	Build or refresh the semantic index
sahara index-report	Inspect indexing coverage and failures
sahara remember [TEXT]	Save durable captured knowledge and index it
sahara recall QUERY	Search only captured memories with metadata filters
sahara memory ...	List, show, edit, delete, or rebuild captured memories
sahara search QUERY	Find files and passages by meaning
sahara ask --snippet QUESTION	Retrieve cited sources and optionally generate an answer
sahara mcp install-claude	Connect Sahara to Claude Desktop, read-only by default
sahara mcp serve	Run MCP retrieval with optional local memory capture

Storage and operational command groups

Command group	Purpose
sahara storage ...	Configure, inspect, or disable optional storage
sahara folder sync ...	Choose which indexed folders also sync
sahara sync/push/pull/status	Inspect and execute storage synchronization
sahara offload/fetch	Free and restore local space with verification
sahara encryption ...	Configure or rotate storage encryption
sahara doctor	Diagnose configuration and connectivity
sahara daemon ...	Manage background watching and synchronization
sahara config ...	Inspect or change configuration

See the complete command reference, or run sahara --help and sahara COMMAND --help for live CLI help.

Documentation

• Getting Started: index-only, local-drive, and AWS paths
• Installation: pipx, virtual environments, and PEP 668
• Command Reference: every CLI command grouped by purpose
• Answer Providers: Ollama and OpenAI setup
• Claude Desktop: installation, MCP contract, and troubleshooting
• Mobile Companion App Spike: evaluation of iOS-first vs cross-platform mobile app paths
• Security: threat model, encryption, and vulnerability reporting
• Roadmap: current scope, planned work, and non-goals
• Architecture: system design and extension points
• Contributing: development setup, tests, and pull requests
• Changelog: release history

License

Sahara is available under the MIT License.