feat: implement UniFFI mobile bindings for iOS and Android

Add localgpt-mobile crate with full UniFFI proc-macro integration:
- LocalGPTClient object with chat, memory, session, and model APIs
- AgentHandle in core for thread-safe Agent access across threads
- Paths::from_root() and Config::load_from_dir() for mobile sandboxes
- Feature-gate FastEmbedProvider behind `embeddings-local` so mobile
  builds can exclude the large fastembed dependency
- iOS build script (XCFramework + Swift bindings via uniffi-bindgen)
- Android Gradle config (cargo-ndk + Kotlin bindings)

Author: yiwang

Cargo.lock

@@ -1218,6 +1218,101 @@ impl Agent {
     }
 }
 
+// ---------------------------------------------------------------------------
+// AgentHandle — thread-safe wrapper for mobile and server consumers
+// ---------------------------------------------------------------------------
+
+/// Thread-safe handle to an Agent. Mobile and server code use this instead of
+/// Agent directly. Wraps in `Arc<tokio::sync::Mutex<Agent>>` so it can be
+/// shared across threads and held across `.await` points.
+#[derive(Clone)]
+pub struct AgentHandle {
+    inner: Arc<tokio::sync::Mutex<Agent>>,
+}
+
+// Compile-time guarantee that AgentHandle is safe to share across threads.
+const _: () = {
+    fn assert_send_sync<T: Send + Sync>() {}
+    fn check() {
+        assert_send_sync::<AgentHandle>();
+    }
+};
+
+impl AgentHandle {
+    /// Create a new handle wrapping an existing Agent.
+    pub fn new(agent: Agent) -> Self {
+        Self {
+            inner: Arc::new(tokio::sync::Mutex::new(agent)),
+        }
+    }
+
+    /// Send a chat message and return the full response text.
+    pub async fn chat(&self, message: &str) -> Result<String> {
+        let mut agent = self.inner.lock().await;
+        agent.chat(message).await
+    }
+
+    /// Start a new session.
+    pub async fn new_session(&self) -> Result<()> {
+        let mut agent = self.inner.lock().await;
+        agent.new_session().await
+    }
+
+    /// Search memory files.
+    pub async fn memory_search(&self, query: &str, max_results: usize) -> Result<Vec<MemoryChunk>> {
+        let agent = self.inner.lock().await;
+        agent.search_memory(query).await.map(|mut results| {
+            results.truncate(max_results);
+            results
+        })
+    }
+
+    /// Read a memory file by name.
+    pub async fn memory_get(&self, filename: &str) -> Result<String> {
+        let agent = self.inner.lock().await;
+        let workspace = agent.memory.workspace();
+        let path = workspace.join(filename);
+        std::fs::read_to_string(&path)
+            .map_err(|e| anyhow::anyhow!("Failed to read {}: {}", filename, e))
+    }
+
+    /// Get the current model name.
+    pub async fn model(&self) -> String {
+        let agent = self.inner.lock().await;
+        agent.model().to_string()
+    }
+
+    /// Switch to a different model.
+    pub async fn set_model(&self, model: &str) -> Result<()> {
+        let mut agent = self.inner.lock().await;
+        agent.set_model(model)
+    }
+
+    /// Get context window usage: (used, usable, total).
+    pub async fn context_usage(&self) -> (usize, usize, usize) {
+        let agent = self.inner.lock().await;
+        agent.context_usage()
+    }
+
+    /// Compact the session history.
+    pub async fn compact_session(&self) -> Result<(usize, usize)> {
+        let mut agent = self.inner.lock().await;
+        agent.compact_session().await
+    }
+
+    /// Clear session history.
+    pub async fn clear_session(&self) {
+        let mut agent = self.inner.lock().await;
+        agent.clear_session();
+    }
+
+    /// Export session as markdown.
+    pub async fn export_markdown(&self) -> String {
+        let agent = self.inner.lock().await;
+        agent.export_markdown()
+    }
+}
+
 /// Welcome message shown on first run (brand new workspace)
 const FIRST_RUN_WELCOME: &str = r#"# Welcome to LocalGPT
 

crates/core/src/agent/mod.rs

@@ -635,6 +635,30 @@ impl Config {
         Ok(config)
     }
 
+    /// Load (or create default) config with all directories rooted under `data_dir`.
+    ///
+    /// Mobile apps use this instead of `load()` since they don't have XDG dirs.
+    pub fn load_from_dir(data_dir: &str) -> Result<Self> {
+        let paths = Paths::from_root(data_dir);
+        paths.ensure_dirs()?;
+        let path = paths.config_file();
+
+        if !path.exists() {
+            let config = Config {
+                paths,
+                ..Config::default()
+            };
+            config.save()?;
+            return Ok(config);
+        }
+
+        let content = fs::read_to_string(&path)?;
+        let mut config: Config = toml::from_str(&content)?;
+        config.paths = paths;
+        config.expand_env_vars();
+        Ok(config)
+    }
+
     pub fn save(&self) -> Result<()> {
         let path = self.paths.config_file();
 

crates/core/src/config/mod.rs

@@ -159,14 +159,18 @@ pub fn hash_text(text: &str) -> String {
 // Local Embedding Provider (fastembed) - Default provider, no API key needed
 // ============================================================================
 
+#[cfg(feature = "embeddings-local")]
 use std::sync::{Arc, Mutex as StdMutex};
 
+#[cfg(feature = "embeddings-local")]
+
 pub struct FastEmbedProvider {
     model: Arc<StdMutex<fastembed::TextEmbedding>>,
     model_name: String,
     dimensions: usize,
 }
 
+#[cfg(feature = "embeddings-local")]
 impl FastEmbedProvider {
     pub fn new(model_name: Option<&str>) -> Result<Self> {
         Self::new_with_cache_dir(model_name, None)
@@ -243,6 +247,7 @@ impl FastEmbedProvider {
     }
 }
 
+#[cfg(feature = "embeddings-local")]
 #[async_trait]
 impl EmbeddingProvider for FastEmbedProvider {
     fn id(&self) -> &str {

crates/core/src/memory/embeddings.rs

@@ -4,9 +4,11 @@ mod search;
 mod watcher;
 mod workspace;
 
+#[cfg(feature = "embeddings-local")]
+pub use embeddings::FastEmbedProvider;
 #[cfg(feature = "gguf")]
 pub use embeddings::LlamaCppProvider;
-pub use embeddings::{EmbeddingProvider, FastEmbedProvider, OpenAIEmbeddingProvider, hash_text};
+pub use embeddings::{EmbeddingProvider, OpenAIEmbeddingProvider, hash_text};
 pub use index::{MemoryIndex, ReindexStats};
 pub use search::MemoryChunk;
 pub use watcher::MemoryWatcher;
@@ -102,31 +104,41 @@ impl MemoryManager {
             .as_str()
         {
             "local" => {
-                let model_name = if memory_config.embedding_model.is_empty()
-                    || memory_config.embedding_model == "text-embedding-3-small"
+                #[cfg(feature = "embeddings-local")]
                 {
-                    None // Use default local model
-                } else {
-                    Some(memory_config.embedding_model.as_str())
-                };
-                let cache_dir = if memory_config.embedding_cache_dir.is_empty() {
-                    None
-                } else {
-                    Some(memory_config.embedding_cache_dir.as_str())
-                };
-                match FastEmbedProvider::new_with_cache_dir(model_name, cache_dir) {
-                    Ok(provider) => {
-                        info!("Using local embedding provider: {}", provider.model());
-                        Some(Arc::new(provider))
-                    }
-                    Err(e) => {
-                        warn!(
-                            "Failed to initialize local embeddings: {}. Falling back to FTS-only search.",
-                            e
-                        );
+                    let model_name = if memory_config.embedding_model.is_empty()
+                        || memory_config.embedding_model == "text-embedding-3-small"
+                    {
+                        None // Use default local model
+                    } else {
+                        Some(memory_config.embedding_model.as_str())
+                    };
+                    let cache_dir = if memory_config.embedding_cache_dir.is_empty() {
                         None
+                    } else {
+                        Some(memory_config.embedding_cache_dir.as_str())
+                    };
+                    match FastEmbedProvider::new_with_cache_dir(model_name, cache_dir) {
+                        Ok(provider) => {
+                            info!("Using local embedding provider: {}", provider.model());
+                            Some(Arc::new(provider))
+                        }
+                        Err(e) => {
+                            warn!(
+                                "Failed to initialize local embeddings: {}. Falling back to FTS-only search.",
+                                e
+                            );
+                            None
+                        }
                     }
                 }
+                #[cfg(not(feature = "embeddings-local"))]
+                {
+                    warn!(
+                        "Local embeddings requested but `embeddings-local` feature is disabled. Falling back to FTS-only search."
+                    );
+                    None
+                }
             }
             "openai" => {
                 // Need OpenAI config for API key

crates/core/src/memory/mod.rs

@@ -158,6 +158,22 @@ impl Paths {
         self.cache_dir.join("embeddings")
     }
 
+    /// Create Paths with all directories rooted under a single base path.
+    ///
+    /// Mobile apps use this to point everything at their app-specific
+    /// document or library directory.
+    pub fn from_root(root: impl Into<PathBuf>) -> Self {
+        let root = root.into();
+        Self {
+            config_dir: root.join("config"),
+            data_dir: root.join("data"),
+            workspace: root.join("data").join("workspace"),
+            state_dir: root.join("state"),
+            cache_dir: root.join("cache"),
+            runtime_dir: None,
+        }
+    }
+
     /// Create all directories with appropriate permissions.
     pub fn ensure_dirs(&self) -> Result<()> {
         let dirs = [

crates/core/src/paths.rs

@@ -12,4 +12,8 @@ name = "localgpt_mobile"
 
 [dependencies]
 localgpt-core = { path = "../core", default-features = false, features = ["embeddings-openai"] }
+uniffi = "0.29"
+tokio = { workspace = true }
 anyhow = { workspace = true }
+thiserror = { workspace = true }
+serde_json = { workspace = true }