{"id":49934794,"url":"https://github.com/anoochit/nami-core","last_synced_at":"2026-05-28T06:09:56.759Z","repository":{"id":354951199,"uuid":"1226120123","full_name":"anoochit/nami-core","owner":"anoochit","description":"A modular, extensible AI agent built on top of adk-rust and the teloxide framework.","archived":false,"fork":false,"pushed_at":"2026-05-17T04:35:19.000Z","size":13037,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-17T06:05:22.508Z","etag":null,"topics":["adk-rust","ai-agents","bots","telegrambot"],"latest_commit_sha":null,"homepage":"https://anoochit.github.io/nami-core/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/anoochit.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-01T02:02:27.000Z","updated_at":"2026-05-17T04:35:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/anoochit/nami-core","commit_stats":null,"previous_names":["anoochit/telegram_bot","anoochit/namiclaw","anoochit/nami-core"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/anoochit/nami-core","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anoochit%2Fnami-core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anoochit%2Fnami-core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anoochit%2Fnami-core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anoochit%2Fnami-core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/anoochit","download_url":"https://codeload.github.com/anoochit/nami-core/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anoochit%2Fnami-core/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33129104,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-16T18:38:32.183Z","status":"online","status_checked_at":"2026-05-17T02:00:05.366Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adk-rust","ai-agents","bots","telegrambot"],"created_at":"2026-05-17T06:05:45.048Z","updated_at":"2026-05-28T06:09:56.751Z","avatar_url":"https://github.com/anoochit.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# nami: AI Bot\n\n\u003e **Note:** This project is currently under active development.\n\nA modular, extensible AI-powered `Nami` built on top of [adk-rust](https://github.com/zavora-ai/adk-rust) and the [teloxide](https://github.com/teloxide/teloxide) framework. This project demonstrates how to leverage modern Rust libraries to build sophisticated AI agents with persistent sessions, filesystem sandbox capabilities, and dynamic persona management.\n\n![Screenshot](screenshots/nami-avatar.png)\n\n## 🚀 Features \u0026 Capabilities\n\n### 🧠 Core Intelligence \u0026 Orchestration\n\n* **Multi-Platform AI**: Powered by Gemini, Anthropic, or any OpenAI-compatible LLM (e.g., ThaiLLM).\n* **Telegram \u0026 LINE Bot Integration**: Seamlessly interact with the agent through popular messaging platforms. Supports persistent sessions and high-performance message processing.\n* **Agent Reflection Service**: A background service that periodically analyzes session logs to synthesize \"Learnings\" (facts, preferences, project context) and automatically update `MEMORIES.md` and searchable memory.\n* **AI Gateway Integration**: Support for high-availability routing via **MLflow Deployments**, enabling load balancing and fallback strategies across multiple LLM providers.\n* **Native PDF \u0026 Marp Slides Rendering**: Directly view PDF documents and render Marp Markdown presentations (using `marp: true` frontmatter) within the WebUI preview canvas.\n* **Specialist Agents**: Ecosystem of specialized agents (`coder`, `researcher`, `writer`, `generalist`, `ralph`) with full access to core tools (filesystem, search, wiki), allowing for autonomous complex task execution.\n* **Native Image Generation**: Implemented a native image generation tool using `gemini-2.5-flash-image-preview`, providing high-quality, efficient visuals directly within the agent's workflow without external script dependencies.\n* **Parallel Task Execution**: A custom `parallel_tasks` tool that orchestrates multiple specialists simultaneously for high-speed multi-tasking.\n* **Autonomous Goal Loops**: A \"Ralph Wiggum\" loop agent that persists through multiple iterations to achieve complex goals, triggered via `/goal`.\n* **Hybrid MCP Support**: Seamlessly connect to both local (stdio-based) and remote (streamable HTTP/SSE) [Model Context Protocol](https://modelcontextprotocol.io/) servers. Tools are automatically namespaced with `mcp_` to prevent collisions.\n* **Native Desktop App (Tauri)**: A premium, cross-platform desktop experience built with Tauri v2. Features an embedded Nami server, native window management, and a high-performance React UI.\n\n### 💻 Rich User Interface\n\n* **Modular React WebUI**: A modern, decomposed component architecture (`ChatHeader`, `MessageList`, `MessageItem`, `ChatInput`) designed for high maintainability, type-safety, and pixel-perfect UX. Features **optimized build chunking** for rapid initial loading.\n* **Modern TUI**: A rich, interactive CLI experience with a custom ASCII banner, animated indicators, **startup discovery counts for MCP/Skills**, pretty error rendering with intelligent hints, and structured layout.\n* **Focused Input Control**: Implements terminal raw mode during processing to block echoes, ensuring a clean and focused agent execution state.\n* **Silent Cancellation**: Support for both `Ctrl+C` and silent `ESC` interruption, allowing users to cancel requests without terminal clutter.\n* **Slash Commands**: Quick access to system functions:\n  * `/new`: Reset current session.\n  * `/parallel`: Run tasks in parallel.\n  * `/goal`: Run autonomous loops.\n  * `/schedule`: Manage automated tasks with cron.\n  * `/plan`: Initialize structured tasks.\n  * `/wiki`: Search the project wiki.\n  * `/memo`: Save information to memory.\n  * `/recall`: Recall information from memory.\n* **@ File Context References**: Reference files from the `workspace/` directly in the CLI using `@path/to/file` with built-in Tab-completion.\n* **Dynamic Persona \u0026 Soul**: Configure the bot's personality and user context via `workspace/AGENT.md` and `workspace/USER.md`. Automatically updated `workspace/MEMORIES.md` tracks personal user facts.\n\n### 📂 Knowledge \u0026 Session Management\n\n* **Long-Term Searchable Memory**: Integrated `adk-memory` with a SQLite backend. This allows the agent to search past conversations for relevant facts and projects across all modes (CLI, Bot, Serve, Browse).\n* **Obsidian-Style Wiki KM**: A transparent, human-readable Knowledge Management system using `.md` files.\n*   `add_wiki_page`: Markdown saving with `[[wikilink]]` syntax.\n*   `get_wiki_graph`: Knowledge graph visualization.\n*   `search_wiki_by_tag`: Filter notes by specific `#tags`.\n*   `create_daily_note`: Journal entries for the current date.\n*   `get_backlinks`: List pages linking to a specific note.\n*   `rename_wiki_page`: Safe renaming with link updates.\n* **Persistent Sessions**: SQLite-backed conversation history keyed by Telegram user ID.\n* **State Management**: A structured JSON-based system for tracking long-running tasks, guided by `workspace/STATE_PROTOCOL.md`.\n*   `init_task`: Initialize new processes with goals and steps.\n*   `update_task`: Progress tracking and persistent context.\n*   `list_active_tasks`: View all in-progress or blocked tasks.\n* **Todo Management**: Built-in task manager for tracking goals and daily items (`add_todo`, `list_todos`, `mark_todo_done`).\n\n### 🛠 Specialized Skills \u0026 Tools\n\n* **Publishing Skills**: Compile workspace documents into distributable formats:\n  * `create-pdf`: Beautifully formatted PDF documents.\n  * `create-epub`: EPUB e-books with BOM sanitization.\n\n### 🧩 Agent Skills\n\nNami Core is designed for extreme extensibility. You can add new capabilities by deploying modules to the `workspace/.skills/` directory.\n\n* **Extensibility Model**: Skills are modular components that bundle specialized scripts and configuration. They allow Nami to perform complex, domain-specific tasks without modifying core code.\n* **Skill Management**: You can manage, create, and validate skills using the `skill-creator` extension.\n* **Workspace Configuration**: The `webui/` workspace uses `pnpm` with a workspace configuration (`pnpm-workspace.yaml`) to optimize dependency management and build reproducibility for `esbuild` and other toolchains.\n\n### Currently Available Skills\n\n* **Book Mockup**: Generate photo-realistic book mockup images using the `image_generator` tool.\n* **CLI Help**: Interactive command references and usage patterns via `cli-help`.\n* **Publishing Suite**: Automate documentation delivery (`create-pdf`, `create-epub`).\n* **Infographic Creator**: Scaffolding and generation for data-rich infographics using the `image_generator` tool.\n* **Website Creator**: Scaffolding for static website projects.\n* **Nami Blog Manager**: Tools for managing blog posts, metadata, and references.\n* **Skill Creator**: Utilities for initializing, packaging, and validating new skills.\n* **System Status**: Monitor and report on system health and agent performance.\n\n*(To add a custom skill, check the `workspace/.skills/skill-creator` documentation for templates and packaging tools.)*\n\n### 🛡 System \u0026 Safety\n\n* **Persistent Task Scheduler**: A `crontab`-style background system that automatically retries unfinished tasks and persists state in `scheduler.json`.\n* **Sandboxed Environment**: Integrated filesystem tools for agent tasks within a `workspace/` directory, protected by a **`.namiignore` policy** (similar to `.gitignore`) to control access permissions.\n* **Observability Stack**: Integrated OpenTelemetry collector and MLflow for robust tracing and experiment tracking.\n* **Live Web Search**: Integrated Google Search via Serper.dev.\n* **Performance Optimized Builds**: Highly tuned release profile with Link-Time Optimization (LTO), single codegen units, and automatic symbol stripping for maximum runtime efficiency.\n* **Modular Architecture**: Organized structure for adding capabilities (Weather, Search, Shell, Wiki, etc.).\n\n## 🛠 Prerequisites\n\n* Rust ([rustup](https://rustup.rs/))\n* A Telegram Bot Token from [@BotFather](https://t.me/BotFather)\n* API Key for your chosen LLM (Gemini, OpenAI, or ThaiLLM)\n* (Optional) [Serper.dev](https://serper.dev/) API Key for Google Search features.\n\n## ⚙️ Configuration\n\n1. Copy `.env.example` to `.env` and configure your credentials:\n\n```bash\ncp .env.example .env\ncp webui/.env.example webui/.env\n```\n\n```text\n# Root .env\nGOOGLE_API_KEY=your_google_api_key_here\nTHAILLM_API_KEY=your_api_key_here\nTELOXIDE_TOKEN=your_telegram_bot_token\nSERPER_API_KEY=your_serper_api_key\nOTEL_COLLECTOR=your_otel_collector_url\nNAMI_API_KEY=your_secure_random_key_here\n\n# webui/.env\nVITE_NAMI_API_KEY=your_secure_random_key_here\n```\n\n1. Customize the Bot's Soul:\n\n* Edit `workspace/AGENT.md` to change the name, personality, and tone.\n* Edit `workspace/USER.md` to provide context about yourself and your preferences.\n\n## 🏃 Getting Started\n\n### Build and Install\n\n1. **Build the application**:\n   The project uses a `Makefile` to automate the build process, including WebUI asset compilation and Rust binary generation.\n\n   ```bash\n   make build\n   ```\n\n   Alternatively, for a standard Rust build (requires `webui/dist/` to be populated):\n\n   ```bash\n   cargo build --release\n   ```\n\n   The generated executable will be found in `target/release/`.\n\n1. **(Optional) Install globally**:\n   To run `nami` from any directory, you can move the binary to a location in your system's `PATH`:\n\n   * **Linux/macOS**:\n\n     ```bash\n     sudo mv target/release/nami /usr/local/bin/\n     ```\n\n   * **Windows**:\n     Add the full path of the `target\\release\\` directory to your system's Environment Variables (PATH).\n\n### Running\n\nThe application provides several run modes:\n\n| Mode | Command | Description |\n| :--- | :--- | :--- |\n| **Initialize** | `nami init` | Initialize project config files and database. |\n| **Telegram Bot** | `nami bot` | Start the interactive Telegram Bot. |\n| **LINE Bot** | `nami line` | Start the LINE Bot webhook server. |\n| **CLI** | `nami cli` | Local interactive terminal agent with rich TUI. |\n| **Run** | `nami run \u003cprompt\u003e` | Execute a single prompt directly from the CLI. |\n| **Server** | `nami serve` | Run as an HTTP service. |\n| **Browse** | `nami browse` | Start server with embedded WebUI. |\n| **Desktop (Dev)** | `make desktop-dev` | Launch the native Tauri desktop app in development mode. |\n| **Desktop (Build)** | `make desktop` | Build the production desktop installer (MSI, DMG, DEB). |\n\n## 🏗 Architecture\n\nThe system supports multiple entry points sharing the same core agent logic:\n\n```mermaid\ngraph TD\n    subgraph EntryPoints [Modes]\n        direction TB\n        Bot[Telegram Bot]\n        Line[LINE Bot]\n        CLI[Interactive CLI]\n        Run[Direct Run]\n        Server[HTTP Server/Browse]\n        Browse[Browse]\n        Desktop[Desktop App]\n    end\n\n    EntryPoints --\u003e Runner[adk-rust Runner]\n    \n    Runner --\u003e Agent[LlmAgent]\n    Runner --\u003e DB[(Session Service)]\n    Runner --\u003e Memory[(Memory Service)]\n    Runner --\u003e Scheduler[Background Scheduler]\n    Runner --\u003e Reflection[Reflection Service]\n    \n    Agent --\u003e LLM[ThaiLLM/Gemini/OpenAI]\n    Agent --\u003e SubAgents[Sub-Agents: Coder, Researcher, Writer, Ralph]\n    Agent --\u003e Tools[Tools: Filesystem, Memory, Soul, etc.]\n    Agent --\u003e Wiki[Obsidian-Style Wiki: Graph, Tags, Daily Notes]\n    Agent --\u003e Persona[AGENT.md \u0026 USER.md]\n\n    Reflection --\u003e Memory\n    Reflection --\u003e UserMemory[\"MEMORIES.md\"]\n    \n    SubAgents --\u003e Agent\n```\n\n## 💡 Development Tips\n\nHere are some best practices for extending and maintaining Nami:\n\n### 🚀 Getting Started \u0026 Production\n\n* **Production Readiness**: For high-traffic bots, migrate `teloxide` from polling to webhooks for better reliability.\n* **Build Optimization**: Use `make build` to ensure all assets (including WebUI) are compiled properly before generating the Rust binary.\n* **Environment Management**: Always manage your credentials via the `.env` file; never hardcode API keys.\n\n### 🧩 Extending Nami\n\n* **New Skills**: You can add new capabilities by deploying modules to the `workspace/.skills/` directory. Use the `skill-creator` extension to initialize, package, and validate them.\n* **Specialist Agents**: For complex tasks, delegate to existing specialists (`coder`, `researcher`, `writer`) via the `parallel_tasks` tool or `/parallel` slash command.\n* **Wiki-First Development**: Always document successful patterns in your `wiki/` vault. Use the \"Wiki-before-Google\" protocol to reduce noise and maintain project-specific context.\n\n### 🧠 System Architecture \u0026 Advanced Features\n\n* **RAG \u0026 Memory**: Consider connecting your `wiki/` vault to a vector database (e.g., Qdrant/Milvus) for semantic search if your knowledge base outgrows simple file-based retrieval.\n* **Tooling Strategy**: When creating new skills, prefer native Rust `#[tool]` macros over external scripts for better performance, type safety, and security.\n* **Agentic Intelligence**: Explore the potential of Meta-Agents that review tool outputs for quality, automatically triggering re-tries or pivots when thresholds aren't met.\n* **Task-Knowledge Bridging**: Automate your daily note templates to automatically pull active tasks from the `StateManager` to maintain a living sync between your todo list and your knowledge base.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanoochit%2Fnami-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanoochit%2Fnami-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanoochit%2Fnami-core/lists"}