Manage Apple Notes via the `memo` CLI on macOS (create, view, edit, delete, search, move, and export notes). Use when a user asks to add a note, list notes, search notes, or manage note folders.
Add this skill
npx mdskills install project-nomos/apple-notesComprehensive CLI wrapper for Apple Notes with clear operations and good coverage
An autonomous AI agent that remembers everything, works everywhere, and never stops learning
Deploy to Slack, Discord, Telegram, WhatsApp — with persistent memory, multi-agent teams, and a web dashboard. All TypeScript, fully open source.
Quick Start · Features · Advanced · Daemon · Channels · Skills · Contributing
Most AI assistants forget you the moment a conversation ends. Nomos doesn't.
Nomos is an autonomous AI agent platform that remembers every interaction, connects to your tools and channels, and gets smarter over time. It runs as a persistent background daemon — always on, always learning — reachable from Slack, Discord, Telegram, WhatsApp, the terminal, or any gRPC/WebSocket client.
It comes with persistent vector memory across sessions and channels, multi-agent team orchestration for complex tasks, smart model routing to optimize cost and quality, 27 bundled skills, a web management dashboard, and built-in image and video generation.
What powers Nomos? Under the hood, Nomos is built on Anthropic's Claude Agent SDK — inheriting the full agent loop, built-in tools, streaming, and compaction. Nomos adds the infrastructure layer on top: memory, channels, teams, scheduling, and a management UI.
# Homebrew (recommended)
brew tap project-nomos/nomos https://github.com/project-nomos/nomos
brew install project-nomos/nomos/nomos
# Then just:
nomos chat
That's it. A browser-based setup wizard handles the rest — database connection, API provider, assistant personality, and channel integrations. Everything is saved encrypted in PostgreSQL. Configuration is stored in ~/.nomos/.env and works from any directory.
Other installation methods
npm install -g @project-nomos/nomos --registry=https://npm.pkg.github.com
git clone https://github.com/project-nomos/nomos.git
cd nomos
cp .env.example .env
# Edit .env with your ANTHROPIC_API_KEY (or OPENROUTER_API_KEY)
docker compose up -d
The agent is accessible via gRPC on port 8766 and WebSocket on port 8765.
docker run -d --name nomos \
-e DATABASE_URL=postgresql://nomos:nomos@host.docker.internal:5432/nomos \
-e ANTHROPIC_API_KEY=sk-ant-... \
-p 8766:8766 -p 8765:8765 \
ghcr.io/project-nomos/nomos:latest
git clone https://github.com/project-nomos/nomos.git
cd nomos
pnpm install
pnpm build
pnpm link --global
nomos chat
| Feature | What it does | |
|---|---|---|
| :brain: | Memory That Persists | Every conversation auto-indexed into pgvector. Recall anything from any session or channel. |
| :speech_balloon: | 6 Channel Integrations | Slack, Discord, Telegram, WhatsApp, iMessage — thin adapters, one agent runtime. |
| :busts_in_silhouette: | Multi-Agent Teams | Coordinator + parallel workers. Hand off complex tasks, get synthesized results. |
| :zap: | Smart Model Routing | Route by complexity across any provider — cloud, local, or hybrid. Cut costs automatically. |
| :globe_with_meridians: | Multiple API Providers | 5 providers supported: direct API, Vertex AI, OpenRouter, Ollama, or custom. |
| :art: | Image & Video Gen | Gemini image + Veo video generation, conversational — just ask. |
| :desktop_computer: | Web Dashboard | Next.js 16 settings UI with setup wizard. No YAML editing. |
| :jigsaw: | 27 Bundled Skills | Three-tier loading: bundled, personal, project. Create your own in minutes. |
| :lock: | Secrets Encrypted at Rest | AES-256-GCM for all API keys and tokens. Auto-key on first run. |
| :brain: | Adaptive Memory | Extracts facts, preferences, corrections. Builds a persistent user model. |
| :arrows_counterclockwise: | Self-Improvement | Nomos can analyze its own code, implement fixes, and open PRs to itself. |
| :globe_with_meridians: | Browser Automation | Playwright-based interactive browser with persistent sessions across tool calls. |
| :gear: | Task Management | Task lifecycle tracking with dependency graphs, auto-unblock, and cancellation. |
| :mag: | LSP Code Intelligence | Go-to-definition, find-references, hover, document symbols via TypeScript LSP. |
| :sleeping: | Sleep & Self-Resume | Agents pause and wake with a prompt — for polling, monitoring, and async waits. |
| :clipboard: | Plan Mode | Agent proposes structured plans for review before making changes. |
Every conversation is automatically indexed into a PostgreSQL-backed vector store. When the agent needs context from a past interaction — even one that happened in a different channel weeks ago — it finds it.
Under the hood: pgvector with hybrid retrieval (vector cosine similarity + full-text search, fused via RRF). Embeddings via Vertex AI gemini-embedding-001 (768 dims). Falls back to FTS when embeddings aren't available.
When enabled (NOMOS_ADAPTIVE_MEMORY=true), the agent extracts structured knowledge from every conversation — facts, preferences, and corrections — using a lightweight LLM call (Haiku by default). Extracted knowledge accumulates into a persistent user model that personalizes responses across sessions.
Nomos has a built-in self-improve skill that lets it analyze its own codebase, implement changes, and open pull requests to itself — all autonomously. Ask it to fix a bug, add a feature, write tests, or refactor its own code.
How it works:
pnpm check, pnpm test, pnpm build)Just say "improve yourself", "add tests for the chunker", or "fix your session cleanup logic" — and review the PR when it's ready.
| Protocol | Port | Purpose |
|---|---|---|
| gRPC | 8766 | Primary protocol for CLI, web, and mobile clients |
| WebSocket | 8765 | Legacy protocol (maintained for backward compatibility) |
| Ink CLI | — | Interactive terminal REPL with streaming markdown |
| Next.js Web UI | 3456 | Settings dashboard and management interface |
A full Next.js 16 app for onboarding, assistant configuration, channel management, and advanced settings — no YAML editing required. Includes a setup wizard (/setup), dashboard overview, per-channel integration management, and database/memory admin.
Add capabilities without modifying core code — drop in a skill file, point to an MCP server, or change a config value:
./skills/), per-user (~/.nomos/skills/), or contribute upstream.nomos/mcp.json| Platform | Mode | Transport |
|---|---|---|
| Slack | Bot Mode | Socket Mode |
| Slack | User Mode | Socket Mode + OAuth (multi-workspace, draft-before-send) |
| Discord | Bot | Gateway |
| Telegram | Bot | grammY |
| Bridge | Baileys | |
| iMessage | Read-only bridge | macOS Messages.app SQLite |
Each adapter is a thin layer (~50-100 LOC). All agent logic is centralized in AgentRuntime; adapters just route messages in and responses out.
Route queries to the right model automatically based on complexity. Works with any provider — Anthropic, OpenRouter, Ollama, or your own endpoint. Use Claude models, open-source local models, or mix and match:
claude-haiku-4-5, llama3, or any local model)claude-sonnet-4-6, mistral-large)claude-opus-4-6, deepseek-r1)Run fully local with Ollama, optimize cloud costs across tiers, or combine local models for simple tasks with cloud models for complex ones.
Enable with NOMOS_SMART_ROUTING=true.
Run Nomos with the provider that fits your setup:
ANTHROPIC_BASE_URLSwitch providers in the Settings UI or via NOMOS_API_PROVIDER. See API Providers for setup details.
API keys, OAuth tokens, and integration secrets never touch the database in plaintext. Everything is encrypted with AES-256-GCM before storage. A key is auto-generated on first run (~/.nomos/encryption.key), or bring your own via ENCRYPTION_KEY.
Hand off a big task and let multiple agents tackle it simultaneously. A coordinator breaks the problem down, spawns parallel workers, and synthesizes their results into one response.
User prompt --> Coordinator --+--> Worker 1 (subtask A) --+
+--> Worker 2 (subtask B) --+--> Coordinator --> Final response
+--> Worker 3 (subtask C) --+
/team prefix: /team Research React vs Svelte and write a comparisonNOMOS_TEAM_MODE=true and NOMOS_MAX_TEAM_WORKERS=3Generate images (via Gemini) and videos (via Veo) directly from conversation. Ask your agent to create a logo, a product mockup, or a short video clip — it handles the API calls, saves the output, and returns the file. Opt-in via Settings UI or env vars.
gemini-3-pro-image-preview. Photorealistic images, illustrations, logos, concept art.veo-3.0-generate-preview. Short cinematic clips with camera and style control.GEMINI_API_KEY from Google AI StudioNomos goes beyond basic chat with a full suite of autonomous agent features:
Full Playwright-based browser control with persistent page sessions. Navigate, click, type, screenshot, and execute JavaScript — all from conversation. Perfect for login flows, form filling, scraping dynamic content, and visual verification.
Tools: browser_navigate, browser_screenshot, browser_click, browser_type, browser_select, browser_evaluate, browser_snapshot, browser_close
Every daemon operation is tracked as a task with lifecycle states (pending → running → completed | failed | killed). Tasks support dependency graphs — declare blockedBy relationships, and tasks auto-start when their dependencies complete. Includes cycle detection and abort-controller-based cancellation.
Tools: task_status, task_kill
Agents can pause execution for up to an hour and resume with a wake-up prompt. Useful for polling deployments, waiting for async operations, or periodic monitoring within a session.
Tool: agent_sleep
For complex tasks, the agent proposes a structured plan (steps, affected files, risk levels) before execution. Plans are stored for review — approve, modify, or reject before any changes are made.
Tool: propose_plan
Language Server Protocol integration providing TypeScript/JavaScript code intelligence. Go-to-definition, find-all-references, hover for type info, and document symbols — powered by typescript-language-server.
Tools: lsp_go_to_definition, lsp_find_references, lsp_hover, lsp_document_symbols
The agent can send messages to your notification channels without being asked — for urgent alerts, monitoring results, or scheduled task output. Messages route through the daemon's channel manager via a process event bridge.
Tool: proactive_send
During multi-agent team execution, workers communicate via an in-memory message bus with priority levels (normal, urgent, blocking). Workers can share intermediate results or report blockers to the coordinator.
Tools: send_worker_message, check_worker_messages
After team workers complete, a read-only adversarial agent runs tests, build, and lint to verify changes. Reports PASS/FAIL/PARTIAL with details.
Four-phase automatic memory cleanup: prune stale chunks (SQL), merge near-duplicates (vector similarity), LLM-powered review (Haiku), and confidence decay for outdated user model entries.
Tool: memory_consolidate
Team workers can operate in isolated git worktrees to avoid conflicts when modifying the same repo concurrently. Auto-cleanup if no changes were made.
The daemon turns Nomos into an always-on, multi-channel AI gateway. It boots an agent runtime, gRPC + WebSocket servers, channel adapters, and a cron engine — then processes incoming messages from all sources through a per-session message queue.
+-------------------+
| Gateway |
| (orchestrator) |
+--------+----------+
|
+------------+--------------+--------------+----------+
| | | | |
+-----v------+ +--v-----+ +-----v--------+ +---v------+ +-v----------+
| gRPC | | WS | | Channel | | Cron | | Draft |
| Server | | Server | | Manager | | Engine | | Manager |
| (port 8766)| | (8765) | | (adapters) | |(schedule)| | (Slack UM) |
+-----+------+ +---+----+ +-----+--------+ +---+------+ +--+---------+
| | | | |
+------+------+------+----+------+-------+------+-----+
|
+--------v---------+
| Message Queue |
| (per-session |
| FIFO) |
+--------+---------+
|
+--------v---------+
| Agent Runtime |
| (Agent SDK) |
+------------------+
SLACK_BOT_TOKEN enables the Slack adapter).nomos daemon start # Background mode
nomos daemon run # Development mode (foreground with logs)
nomos daemon status # Check if running
nomos daemon logs # Tail logs
Each channel adapter is automatically registered when its required environment variables are present. For detailed setup guides, see docs/integrations/.
Nomos integrates with Slack via nomos-slack-mcp, an external MCP server that provides channel/user name resolution, message formatting, search, reactions, and multi-workspace support.
# Add a Slack workspace (interactive OAuth or manual token)
npx nomos-slack-add-workspace
# Or for daemon bot mode (receives messages via Socket Mode):
SLACK_BOT_TOKEN=xoxb-... # Bot User OAuth Token
SLACK_APP_TOKEN=xapp-... # App-Level Token (Socket Mode)
SLACK_ALLOWED_CHANNELS=C123,C456 # Optional: restrict to specific channels
nomos-slack-mcp uses user tokens (xoxp-) stored in ~/.nomos/slack/config.json, supporting #channel-name and @username resolution, message search, status updates, and reactions.
DISCORD_BOT_TOKEN=... # Bot token from Discord Developer Portal
DISCORD_ALLOWED_CHANNELS=123456,789012 # Optional: restrict to specific channels
TELEGRAM_BOT_TOKEN=... # Token from @BotFather
TELEGRAM_ALLOWED_CHATS=123456,-789012 # Optional: restrict to specific chats
WHATSAPP_ENABLED=true
WHATSAPP_ALLOWED_CHATS=15551234567@s.whatsapp.net
Uses Baileys with QR code auth (no Meta Business API required). Auth state persisted to ~/.nomos/whatsapp-auth/.
| Integration | MCP Server | Guide |
|---|---|---|
| Google Ads | google-ads-mcp | Setup |
| Google Analytics | analytics-mcp | Setup |
| Google Workspace | @googleworkspace/cli | Setup |
| Provider | Description | Guide |
|---|---|---|
| Anthropic (default) | Direct Anthropic API | Set ANTHROPIC_API_KEY |
| Vertex AI | Google Cloud Vertex AI | Set CLAUDE_CODE_USE_VERTEX=1 + GCP credentials |
| OpenRouter | Anthropic models via OpenRouter | Setup guide |
| Ollama | Local models via LiteLLM proxy | Setup guide |
| Custom | Any Anthropic-compatible endpoint | Set ANTHROPIC_BASE_URL |
Skills are markdown files (SKILL.md) with YAML frontmatter that provide domain-specific instructions to the agent. Loaded from three tiers: bundled (skills/) -> personal (~/.nomos/skills/) -> project (./skills/).
All 33 bundled skills
| Skill | Description |
|---|---|
algorithmic-art | Generative art and creative coding |
apple-notes | Apple Notes integration |
apple-reminders | Apple Reminders integration |
brand-guidelines | Brand and style guide creation |
canvas-design | Canvas-based design generation |
digital-marketing | Google Ads + Analytics campaigns, team mode analysis workflows |
discord | Discord bot and integration help |
doc-coauthoring | Collaborative document writing |
docx | Word document generation |
frontend-design | Frontend UI/UX design guidance |
github | GitHub workflow and PR management |
image-generation | Image generation with Gemini (prompts, styles, capabilities) |
gws-gmail | Gmail API (messages, drafts, labels) |
gws-drive | Google Drive (files, folders, permissions) |
gws-calendar | Google Calendar (events, scheduling) |
gws-sheets | Google Sheets (read, write, append) |
gws-docs | Google Docs (create, read, edit) |
gws-slides | Google Slides (presentations) |
gws-shared | Google Workspace shared auth and conventions |
internal-comms | Internal communications drafting |
mcp-builder | MCP server development |
pdf | PDF document generation |
pptx | PowerPoint presentation generation |
self-improve | Self-improvement and learning |
skill-creator | Create new skills from prompts |
slack | Slack app and integration help |
slack-gif-creator | Slack GIF creation |
telegram | Telegram bot and integration help |
theme-factory | Theme and color scheme generation |
video-generation | Video generation with Veo (camera, styles, prompt guidance) |
weather | Weather information and forecasts |
web-artifacts-builder | Web artifact (HTML/CSS/JS) creation |
webapp-testing | Web application testing guidance |
whatsapp | WhatsApp integration help |
xlsx | Excel spreadsheet generation |
mkdir -p ~/.nomos/skills/my-skill
cat > ~/.nomos/skills/my-skill/SKILL.md dist/index.js
pnpm typecheck # TypeScript type check (tsc --noEmit)
pnpm test # Run tests (vitest)
pnpm lint # Lint (oxlint)
pnpm check # Full check (format + typecheck + lint)
pnpm daemon:dev # Run daemon in dev mode (tsx)
See CONTRIBUTING.md for development setup, architecture, code conventions, and how to submit pull requests.
Configuration Reference
Configuration is loaded with the following precedence: Database > environment variables > hardcoded defaults. Environment variables are loaded from ~/.nomos/.env (primary) and .env in the current directory (fallback). API keys and secrets are stored encrypted (AES-256-GCM) in the integrations table.
| Variable | Description | Default |
|---|---|---|
DATABASE_URL | PostgreSQL connection string (must have pgvector) | -- |
| Variable | Description | Default |
|---|---|---|
ANTHROPIC_API_KEY | Anthropic direct API key | -- |
CLAUDE_CODE_USE_VERTEX | Set to 1 to use Vertex AI | -- |
GOOGLE_CLOUD_PROJECT | Google Cloud project ID (for Vertex AI) | -- |
CLOUD_ML_REGION | Vertex AI region | -- |
| Variable | Description | Default |
|---|---|---|
NOMOS_MODEL | Default Claude model | claude-sonnet-4-6 |
NOMOS_PERMISSION_MODE | Tool permission mode (default, acceptEdits, plan, dontAsk, bypassPermissions) | acceptEdits |
NOMOS_SMART_ROUTING | Enable complexity-based model routing | false |
NOMOS_TEAM_MODE | Enable multi-agent team orchestration | false |
NOMOS_MAX_TEAM_WORKERS | Max parallel workers in team mode | 3 |
NOMOS_ADAPTIVE_MEMORY | Enable knowledge extraction and user model learning | false |
NOMOS_IMAGE_GENERATION | Enable image generation via Gemini | false |
GEMINI_API_KEY | Gemini API key (shared by image and video generation) | -- |
NOMOS_VIDEO_GENERATION | Enable video generation via Veo | false |
ANTHROPIC_BASE_URL | Custom Anthropic API base URL (Ollama, LiteLLM, etc.) | -- |
| Variable | Description | Default |
|---|---|---|
SLACK_BOT_TOKEN | Slack Bot User OAuth Token | -- |
SLACK_APP_TOKEN | Slack App-Level Token (Socket Mode) | -- |
DISCORD_BOT_TOKEN | Discord bot token | -- |
TELEGRAM_BOT_TOKEN | Telegram bot token from @BotFather | -- |
WHATSAPP_ENABLED | Set to true to enable WhatsApp | -- |
See .env.example for the complete list of all configuration options.
gRPC & WebSocket Protocols
Clients communicate via gRPC on localhost:8766. The service is defined in proto/nomos.proto.
service NomosAgent {
rpc Chat (ChatRequest) returns (stream AgentEvent);
rpc Command (CommandRequest) returns (CommandResponse);
rpc GetStatus (Empty) returns (StatusResponse);
rpc ListSessions (Empty) returns (SessionList);
rpc GetSession (SessionRequest) returns (SessionResponse);
rpc ListDrafts (Empty) returns (DraftList);
rpc ApproveDraft (DraftAction) returns (DraftResponse);
rpc RejectDraft (DraftAction) returns (DraftResponse);
rpc Ping (Empty) returns (PongResponse);
}
The .proto file can generate native clients for iOS (Swift), Android (Kotlin), and other platforms.
The WebSocket server runs on ws://localhost:8765 for backwards compatibility. See the protocol documentation for message formats.
Slash Commands
| Command | Description |
|---|---|
/clear | Clear conversation context |
/compact | Compact conversation to reduce context usage |
/status | Show system status overview |
/model | Switch model |
/thinking | Set thinking level (off, minimal, low, medium, high, max) |
/profile set | Set profile field (name, timezone, workspace, instructions) |
/identity set | Set agent identity (name, emoji) |
/skills | List loaded skills |
/memory search | Search the vector memory |
/drafts | List pending draft responses (Slack User Mode) |
/approve | Approve a draft |
/config set | Change a setting |
/tools | List available tools |
/mcp | List MCP servers |
/quit | Exit Nomos |
Settings Web UI
A local Next.js app at settings/ for managing your assistant via the browser (port 3456).
| Route | Description |
|---|---|
/setup | 5-step onboarding wizard (database, API, personality, channels, ready) |
/dashboard | Overview: assistant status, model, active channels, memory stats, quick actions |
/settings | Assistant identity, API config, model, advanced settings |
/integrations | Channel overview and per-platform configuration |
/admin/database | Database connection and migration status |
/admin/memory | Memory store stats and management |
nomos settings # Start on http://localhost:3456 and open browser
nomos settings --port 4000 # Custom port
Contributions are welcome. See CONTRIBUTING.md for development setup, testing, code conventions, and how to submit pull requests.
Install via CLI
npx mdskills install project-nomos/apple-notesApple Notes is a free, open-source AI agent skill. Manage Apple Notes via the `memo` CLI on macOS (create, view, edit, delete, search, move, and export notes). Use when a user asks to add a note, list notes, search notes, or manage note folders.
Install Apple Notes with a single command:
npx mdskills install project-nomos/apple-notesThis downloads the skill files into your project and your AI agent picks them up automatically.
Apple Notes works with Claude Code, Claude Desktop, Cursor, Vscode Copilot, Windsurf, Continue Dev, Gemini Cli, Amp, Roo Code, Goose. Skills use the open SKILL.md format which is compatible with any AI coding agent that reads markdown instructions.