Choosing a Posture

Mooshik supports two deployment postures: Local and Shared.

Your posture determines where your memory graph is stored, how embeddings are generated, and which model powers the companion.

Posture Comparison

Feature	Local Posture	Shared Posture
Store Kind	sqlite	postgres
Store Location	Local file (~/.mooshik/mooshik.db)	PostgreSQL instance with pgvector
Embedder Kind	bge_m3	gemini
Embedding Model	BGE-M3 (1024 dimensions)	gemini-embedding-001 (1536 dimensions)
Companion Auth	none or bearer	google
Companion Endpoint	Local /v1 endpoint (llama.cpp, Ollama)	Vertex AI endpoint
Companion Model	local-model (e.g. Qwen, Llama)	google/gemini-3.7-flash
Network Access	Completely offline	Requires internet access for Vertex AI
Multi-Machine Sync	No (single machine)	Yes (shared cross-machine graph)

The Local Posture

The local posture keeps all data on your machine.

• Offline capability: Works without internet access.
• Privacy: No prompts, embeddings, or graph nodes leave your computer.
• Requirements: Requires a local model runner (such as llama-server or Ollama) serving an OpenAI-compatible /v1 endpoint.

Example ~/.mooshik/config.toml for the local posture:

[vault]
provider = "keyring"

[store]
kind = "sqlite"
path = "/home/you/.mooshik/mooshik.db"

[embedder]
kind = "bge_m3"
dim = 1024

[companion]
base_url = "http://127.0.0.1:8080/v1"
model = "local-model"
context_window = 32768
temperature = 0.2

The Shared Posture

The shared posture connects multiple computers to a single graph memory.

• Continuous cross-machine memory: Your desktop, laptop, and background batch jobs share the same knowledge graph.
• Hosted inference: Uses google/gemini-3.7-flash via Vertex AI for fast companion responses.
• Requirements: A PostgreSQL database with the vector extension (such as Google Cloud SQL) and Google Cloud Vertex AI access.
• Credentials: Either a gcloud login, which is gcloud auth application-default login followed by gcloud auth application-default set-quota-project YOUR_PROJECT, or a service-account key file. Run both gcloud commands before mooshik init, since Mooshik reads credentials at startup. See Guided Setup.

Example ~/.mooshik/config.toml for the shared posture:

[vault]
provider = "keyring"

[store]
kind = "postgres"
dsn_secret = "store-dsn"

[embedder]
kind = "gemini"
dim = 1536
gemini_project = "my-project"
gemini_location = "us-central1"
gemini_model = "gemini-embedding-001"
gemini_credentials = "/path/to/credentials.json"

[companion]
auth = "google"
google_project = "my-project"
google_location = "global"
google_credentials = "/path/to/credentials.json"
model = "google/gemini-3.7-flash"
context_window = 32768
temperature = 0.2

The Vertex Location Trap

The shared posture uses two different Google Cloud locations for inference and embeddings:

• Inference (companion.google_location): Must be global. Vertex AI serves Gemini 3.x Flash models from global only. Requesting Gemini 3.x in a specific regional endpoint returns a 404 NOT_FOUND error.
• Embedding (embedder.gemini_location): Must be us-central1. The gemini-embedding-001 model is hosted in regional endpoints.

Do not attempt to make these two settings identical.

Switching Postures

You can switch postures at any time by running mooshik init.

[!WARNING] Switching between bge_m3 and gemini embedders changes vector dimensions and models. Vectors generated by different models cannot be compared. Switching embedders requires creating a new session or re-indexing your graph.