nemoris 0.1.0

package/.env.example

@@ -0,0 +1,49 @@
+# ============================================================
+# Nemoris — Environment Variables
+# Copy this file to .env and fill in your values
+# Run: nemoris setup  (walks you through the essentials)
+# ============================================================
+
+# ---- Anthropic (required for cloud AI) --------------------
+NEMORIS_ANTHROPIC_API_KEY=          # Get from console.anthropic.com
+
+# ---- OpenRouter (optional — fallback + Perplexity search) --
+OPENROUTER_API_KEY=                  # Get from openrouter.ai
+
+# ---- Telegram (required for Telegram channel) -------------
+NEMORIS_TELEGRAM_BOT_TOKEN=          # From @BotFather on Telegram
+NEMORIS_TELEGRAM_CHAT_ID=            # Your Telegram user/chat ID
+NEMORIS_ALLOW_ANY_CHAT=false         # true = accept messages from any chat (dev only)
+NEMORIS_ALLOW_TELEGRAM_DELIVERY=true # false = suppress outbound Telegram messages
+
+# ---- Slack (optional) -------------------------------------
+SLACK_BOT_TOKEN=                     # xoxb-... from Slack App dashboard
+SLACK_SIGNING_SECRET=                # From Slack App dashboard → Basic Info
+
+# ---- Ollama (optional — local inference) ------------------
+# Install from https://ollama.com then run: nemoris setup ollama
+OLLAMA_BASE_URL=http://localhost:11434   # Override if Ollama runs on a different port
+NEMORIS_OLLAMA_MODEL=kimi-k2.5          # Default local model
+
+# ---- Runtime tuning (optional) ----------------------------
+NEMORIS_RATE_LIMIT_MAX=10            # Max messages per window (default: 10)
+NEMORIS_RATE_LIMIT_WINDOW_MS=60000   # Rate limit window in ms (default: 60000)
+NEMORIS_IDENTITY_CACHE_TTL_MS=300000 # Identity cache TTL in ms (default: 5 min)
+
+# ---- Provider mode (required at startup) ------------------
+NEMORIS_ALLOW_PROVIDER_MODE=remote   # "remote" or "local"
+NEMORIS_ALLOW_REMOTE_PROVIDER_MODE=true
+
+# ---- Advanced / internal ----------------------------------
+NEMORIS_AGENT_NAME=                  # Override default agent name
+NEMORIS_LIVE_ROOT=                   # Override live root path
+NEMORIS_INIT_MODE=                   # "fresh" forces re-initialisation
+NEMORIS_QUIET=false                  # Suppress startup logs
+ANTHROPIC_THINKING_ENABLED=false     # Enable /think extended thinking mode
+
+# ---- Semantic embeddings (local via Ollama nomic-embed-text) --
+# NEMORIS_ALLOW_EMBEDDINGS=1
+# NEMORIS_ALLOW_REMOTE_EMBEDDINGS=0
+
+# ---- Feature flags ----------------------------------------
+NEMORIS_WEBHOOK_SECRET=              # Optional — validates Telegram webhook payloads

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lee Anderson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,209 @@
+<p align="left">
+  <img src="assets/logo.svg" alt="Nemoris" width="600">
+</p>
+
+[![npm](https://img.shields.io/npm/v/nemoris)](https://npmjs.com/package/nemoris)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Tests](https://github.com/amzer24/nemoris/actions/workflows/main.yml/badge.svg)](https://github.com/amzer24/nemoris/actions/workflows/main.yml)
+[![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](https://nodejs.org)
+
+A personal AI agent runtime. Runs locally. Persistent memory, delivery guarantees, scheduled jobs, and self-healing — no cloud, no lock-in.
+
+```bash
+npm install -g nemoris
+```
+
+Most agent frameworks give you a chatbot that forgets everything between sessions and silently drops messages when something breaks.
+
+---
+
+## Why Nemoris
+
+Nemoris fixes this with three things that actually work:
+
+### Active Memory
+SQLite-backed semantic memory with embeddings, salience scoring, deduplication, and compaction. Your agents remember what matters across sessions — not just within them.
+
+### Delivery Guarantees
+Criticality-classified message delivery with retry pipelines, ack tracking, and pending decision management. Messages don't get lost. Decisions don't fall through cracks.
+
+### Task Contracts
+Structured task lifecycle with state machines, escalation chains, and explicit completion signals. When an agent starts something, it finishes it — or tells you why it didn't.
+
+---
+
+## Quick Start
+
+```bash
+# Install globally
+npm install -g nemoris
+
+# Interactive setup (~2 minutes)
+nemoris setup
+```
+
+You'll need an API key from Anthropic or OpenRouter — or just use Ollama for free local models.
+
+```bash
+# Start the daemon
+nemoris start
+```
+
+The setup wizard connects a provider, optionally wires up Telegram, and starts your first agent. Coming from OpenClaw? Run `nemoris migrate` — agents, jobs, and memory import in under 2 minutes.
+
+### Requirements
+
+- **Node.js >= 22**
+- **Ollama** (optional — free local models via [ollama.ai](https://ollama.ai))
+
+---
+
+## Providers
+
+- **Anthropic** (Claude) — direct API with prompt caching
+- **OpenRouter** — access to 100+ models
+- **Ollama** — free local models, zero cloud dependency
+
+---
+
+## What You Get
+
+| Feature | What it does |
+|---------|-------------|
+| **Active Memory** | Semantic search, embeddings, salience scoring, dedup, compaction — all in SQLite |
+| **Self-Healing** | Nurse system with health probes, automatic repair, rule promotion, severity-tiered notifications |
+| **Exec Approval** | Side-effect gating — approve or deny shell commands from Telegram before they run |
+| **Task Contracts** | State machine lifecycle, escalation chains, completion pings, multi-agent coordination |
+| **Context Compaction** | DAG-based session summarisation — long conversations stay fast and relevant |
+| **Runtime Resilience** | Circuit breaker, near-duplicate detection, idempotent retries |
+| **Session Search** | FTS5 full-text search over conversation history via `/search` and `session_search` tool |
+| **MCP Consumer** | Connect external MCP servers as native tools — filesystem, GitHub, databases, anything |
+| **Vision** | Telegram photos processed by vision-capable models |
+| **Scheduled Jobs** | Cron-triggered and ad-hoc jobs land in the same unified queue as interactive messages |
+| **Multi-Agent** | Agents trigger each other via task contracts and completion pings |
+| **Telegram** | Chat with agents from your phone — slash commands, photos, reactions |
+| **OpenClaw Migration** | Full import of agents, jobs, and memory |
+
+---
+
+## CLI Commands
+
+```bash
+nemoris setup          # Interactive setup wizard
+nemoris start          # Start the daemon
+nemoris stop           # Stop the daemon
+nemoris status         # Show running agents, jobs, providers
+nemoris doctor         # Health check and dependency report
+nemoris migrate        # Import from OpenClaw
+nemoris mcp list       # Show connected MCP servers and tools
+```
+
+## Telegram Commands
+
+| Command | Description |
+|---------|-------------|
+| `/switch` | Switch who you're talking to |
+| `/who` | Show current agent |
+| `/status` | System status and usage |
+| `/cost` | Today / week / month spending totals |
+| `/search` | Search conversation history |
+| `/logs` | Tail recent daemon logs |
+| `/model` | Change AI model — `/model sonnet \| haiku \| opus` |
+| `/clear` | Start a fresh conversation |
+| `/stop` | Cancel current task |
+| `/compact` | Free up memory (keeps recent turns) |
+| `/exec_approve <id>` | Approve a pending exec command |
+| `/exec_deny <id>` | Deny a pending exec command |
+| `/agents` | List available agents |
+| `/help` | Show all commands |
+
+---
+
+## Architecture
+
+Nemoris runs as a single background daemon on your machine — no Docker, no cloud. Inbound messages enter a unified queue alongside scheduled jobs. The drain loop hydrates context (memory, history, tools), calls the LLM, executes tool calls with approval gating, writes to memory, and delivers responses. The Nurse watches everything and repairs what breaks.
+
+```
+  Telegram / MCP / CLI
+          │
+    ┌─────▼──────┐
+    │  Inbound    │
+    │  Handler    │
+    └─────┬──────┘
+          │
+    ┌─────▼──────┐     ┌────────────┐
+    │  Unified    │◄────│  Scheduled │
+    │  Queue      │     │  Jobs      │
+    └─────┬──────┘     └────────────┘
+          │
+    ┌─────▼──────┐
+    │  Drain      │
+    │  Loop       │
+    └─────┬──────┘
+          │
+    ┌─────▼──────────────────────────────────┐
+    │  Executor                               │
+    │  ┌──────┐  ┌───────┐  ┌──────────────┐ │
+    │  │ LLM  ├──► Tools  ├──► Memory Write │ │
+    │  └──────┘  └───┬───┘  └──────────────┘ │
+    │                │                        │
+    │         ┌──────▼──────┐                 │
+    │         │ Exec Approve│                 │
+    │         └─────────────┘                 │
+    └─────┬──────────────────────────────────┘
+          │
+    ┌─────▼──────┐     ┌────────────┐
+    │  Delivery   │     │  Nurse     │
+    │  Pipeline   │     │  (healing) │
+    └─────┬──────┘     └──────┬─────┘
+          │                   │
+    ┌─────▼───┐         ┌────▼─────┐
+    │Telegram │         │ Probes & │
+    │Agent    │         │ Repair   │
+    │Webhook  │         └──────────┘
+    └─────────┘
+```
+
+---
+
+## Platform Support
+
+| Platform | Service Manager | Status |
+|----------|----------------|--------|
+| macOS | launchd | Full support |
+| Linux | systemd (user) | Full support |
+| Windows | PM2 | Supported (WSL2 recommended) |
+
+---
+
+## Development
+
+Requires Node.js >= 22.
+
+```bash
+git clone https://github.com/amzer24/nemoris.git
+cd nemoris
+npm install
+npm test           # 1179 tests
+npm run test:e2e   # End-to-end tests
+```
+
+Agents are configured in TOML with their own identity files, memory, tool access, and workspace context. See `docs/` for specs and architecture decisions.
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
+
+Please read our [Code of Conduct](CODE_OF_CONDUCT.md) before participating.
+
+## Security
+
+See [SECURITY.md](SECURITY.md) for our security policy and how to report vulnerabilities.
+
+---
+
+## License
+
+[MIT](LICENSE)

package/SECURITY.md

@@ -0,0 +1,119 @@
+# Security Policy
+
+Nemoris is a local-first agent runtime for a single operator on a machine they control. It is powerful software: it can execute tools, talk to remote model providers, store local state, and deliver messages through channels like Telegram and Slack. Please read this file before deploying it on a machine that holds sensitive data.
+
+## Supported Versions
+
+Security fixes are currently targeted at:
+
+- the latest `main` branch
+- the latest published npm release
+
+Older versions may not receive backported fixes.
+
+## Reporting a Vulnerability
+
+Please do not open public GitHub issues for security vulnerabilities.
+
+Use one of these private channels instead:
+
+- GitHub Security Advisories: [Report a vulnerability](https://github.com/amzer24/nemoris/security/advisories/new)
+- Email fallback: `amzer24@gmail.com`
+
+Please include:
+
+- what you observed
+- affected version or commit
+- the smallest reliable reproduction
+- impact assessment
+- any mitigations you already tested
+
+I will acknowledge a good-faith report as quickly as possible and work toward a coordinated fix before public disclosure.
+
+## Threat Model
+
+Nemoris is designed for:
+
+- a single user
+- a machine or account they control
+- explicitly configured workspaces and delivery channels
+- operator-reviewed tool use and provider configuration
+
+Nemoris is not designed to be:
+
+- a hardened multi-tenant sandbox
+- a safe environment for arbitrary untrusted users
+- a drop-in remote execution service for strangers
+
+If you need those guarantees, isolate Nemoris at the OS, VM, or container level rather than relying on prompt rules alone.
+
+## What Stays Local vs What Leaves the Machine
+
+By default, Nemoris stores its runtime state locally under the install root, including:
+
+- config manifests
+- local state and SQLite databases
+- auth profiles in `state/auth-profiles.json`
+- daemon logs
+
+Data leaves the machine when you enable external integrations, including:
+
+- LLM provider calls to Anthropic, OpenRouter, OpenAI Codex, or other configured providers
+- Telegram or Slack delivery and inbound messaging
+- MCP servers or other network-capable tools
+
+Treat those integrations as trust boundaries. Only enable the ones you intend to use.
+
+## Security Expectations and Non-Goals
+
+Nemoris aims to be secure by default for a personal local runtime, but there are important limits:
+
+- tool access is policy-bounded, but the runtime is still operating on your machine
+- remote providers can receive prompt content, tool output, and uploaded content needed to complete a turn
+- delivery adapters can send content to third-party services once enabled
+- local state files should be treated as sensitive operator data
+
+This means Nemoris should be run with the least privilege that still lets it do useful work.
+
+## Safe Deployment Guidance
+
+Recommended:
+
+- run Nemoris as your own user account, not a shared account
+- keep workspaces narrow and intentional
+- use least-privilege provider tokens
+- leave delivery gates disabled until you are ready for live sends
+- keep `.env` and `state/auth-profiles.json` private
+- use explicit allowlists for Telegram/Slack users rather than broad access
+- keep the runtime updated
+
+Not recommended:
+
+- pointing it at your whole home directory as a workspace
+- running it as root
+- sharing one install across untrusted users
+- enabling remote delivery channels before validating auth and allowlists
+
+## Sensitive Files
+
+Handle these as secrets:
+
+- `.env`
+- `state/auth-profiles.json`
+- any provider or delivery tokens
+- daemon logs that may contain identifiers or operational details
+
+Do not paste those files into public issues.
+
+## Security-Focused Operations
+
+Useful commands when validating a setup:
+
+```bash
+nemoris doctor
+nemoris status
+nemoris logs
+npm run publish:check
+```
+
+If you are recovering from a token, install, or daemon problem, see [`docs/RECOVERY-FLOWS.md`](docs/RECOVERY-FLOWS.md).

package/bin/nemoris

@@ -0,0 +1,46 @@
+#!/bin/sh
+set -eu
+
+SCRIPT_PATH=$0
+while [ -L "$SCRIPT_PATH" ]; do
+  SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$SCRIPT_PATH")" && pwd)
+  LINK_TARGET=$(readlink "$SCRIPT_PATH")
+  case "$LINK_TARGET" in
+    /*) SCRIPT_PATH="$LINK_TARGET" ;;
+    *) SCRIPT_PATH="$SCRIPT_DIR/$LINK_TARGET" ;;
+  esac
+done
+
+ROOT_DIR=$(CDPATH= cd -- "$(dirname -- "$SCRIPT_PATH")/.." && pwd)
+FILTERED_NODE_OPTIONS=""
+SKIP_NEXT=0
+
+for ARG in ${NODE_OPTIONS-}; do
+  if [ "$SKIP_NEXT" = "1" ]; then
+    SKIP_NEXT=0
+    case "$ARG" in
+      *disable_autoselectfamily.js*) continue ;;
+      *) FILTERED_NODE_OPTIONS="$FILTERED_NODE_OPTIONS $ARG"; continue ;;
+    esac
+  fi
+
+  case "$ARG" in
+    --require)
+      SKIP_NEXT=1
+      ;;
+    --require=*disable_autoselectfamily.js*)
+      ;;
+    *)
+      FILTERED_NODE_OPTIONS="$FILTERED_NODE_OPTIONS $ARG"
+      ;;
+  esac
+done
+
+FILTERED_NODE_OPTIONS=$(printf "%s" "$FILTERED_NODE_OPTIONS" | sed 's/^ //')
+if [ -n "$FILTERED_NODE_OPTIONS" ]; then
+  export NODE_OPTIONS="$FILTERED_NODE_OPTIONS"
+else
+  unset NODE_OPTIONS
+fi
+
+exec node "$ROOT_DIR/src/cli.js" "$@"

package/config/agents/agent.toml.example

@@ -0,0 +1,28 @@
+# Example agent configuration — copy this to create your own agent.
+#
+# cp agent.example.toml myagent.toml
+# Then edit the values below.
+
+id = "myagent"
+primary_lane = "interactive_primary"
+memory_policy = "default"
+tool_policy = "interactive_safe"
+soul_ref = "config/identity/myagent-soul.md"
+purpose_ref = "config/identity/myagent-purpose.md"
+
+# Where this agent reads/writes workspace files.
+# Relative to the Nemoris install directory.
+workspace_root = "workspace"
+
+# Files loaded into context at the start of each turn (optional).
+# workspace_context_files = ["MEMORY.md"]
+# workspace_context_cap = 8000
+
+[limits]
+max_tokens_per_turn = 16000
+max_tool_calls_per_turn = 6
+max_runtime_seconds = 120
+
+[access]
+workspace = "rw"
+network = "restricted"

package/config/agents/default.toml

@@ -0,0 +1,22 @@
+id = "assistant"
+primary_lane = "interactive_primary"
+memory_policy = "default"
+tool_policy = "interactive_safe"
+soul_ref = "config/identity/default-soul.md"
+purpose_ref = "config/identity/default-purpose.md"
+workspace_root = "~/.nemoris/workspace"
+
+[interaction_contract]
+ack_mode = "immediate"
+progress_mode = "milestone"
+notify_on_done = true
+notify_on_error = true
+
+[limits]
+max_tokens_per_turn = 16000
+max_tool_calls_per_turn = 6
+max_runtime_seconds = 120
+
+[access]
+workspace = "rw"
+network = "restricted"

package/config/agents/orchestrator.toml

@@ -0,0 +1,18 @@
+id = "orchestrator"
+soul_ref = "config/identity/orchestrator-soul.md"
+purpose_ref = "config/identity/orchestrator-purpose.md"
+primary_lane = "local_cheap"
+fallback_lane = "interactive_fallback"
+tool_policy = "orchestrator"
+memory_policy = "orchestrator"
+
+[limits]
+max_tokens_per_turn = 2700
+
+[routing.static]
+"heartbeat-check" = "heartbeat"
+
+[routing.dynamic]
+enabled = true
+model_lane = "local_cheap"
+max_routing_tokens = 500

package/config/delivery.toml

@@ -0,0 +1,73 @@
+default_interactive_profile = "gateway_telegram_main"
+default_scheduler_profile = "shadow_scheduler"
+default_interactive_profile_standalone = "standalone_operator"
+default_peer_profile_standalone = "standalone_peer"
+
+[profiles.shadow_scheduler]
+adapter = "shadow"
+enabled = true
+target = "scheduler_log"
+
+[profiles.gateway_preview_main]
+adapter = "openclaw_cli"
+enabled = true
+channel = "telegram"
+account_id = "default"
+chat_id = "7781763328"
+silent = true
+dry_run = true
+
+[profiles.gateway_telegram_main]
+adapter = "openclaw_cli"
+enabled = false
+channel = "telegram"
+account_id = "default"
+chat_id = "7781763328"
+silent = true
+dry_run = false
+
+[profiles.peer_preview]
+adapter = "openclaw_peer"
+enabled = true
+dry_run = true
+timeout_ms = 15000
+
+[profiles.peer_live]
+adapter = "openclaw_peer"
+enabled = false
+dry_run = false
+timeout_ms = 15000
+
+[profiles.telegram_main]
+adapter = "telegram"
+enabled = false
+channel = "telegram"
+account_id = "default"
+chat_id = "7781763328"
+bot_token_env = "NEMORIS_TELEGRAM_BOT_TOKEN"
+
+[profiles.standalone_operator]
+adapter = "local_file"
+enabled = true
+target = "operator"
+
+[profiles.standalone_peer]
+adapter = "local_file"
+enabled = true
+target = "peer_queue"
+
+[profiles.standalone_http_operator]
+adapter = "standalone_http"
+enabled = false
+dry_run = false
+base_url = "${NEMORIS_TRANSPORT_URL}"
+auth_token_env = "NEMORIS_TRANSPORT_TOKEN"
+timeout_ms = 5000
+
+[profiles.standalone_http_peer]
+adapter = "standalone_http"
+enabled = false
+dry_run = false
+base_url = "${NEMORIS_TRANSPORT_URL}"
+auth_token_env = "NEMORIS_TRANSPORT_TOKEN"
+timeout_ms = 5000

package/config/embeddings.toml

@@ -0,0 +1,5 @@
+enabled = true
+provider = "ollama"
+model = "ollama/nomic-embed-text"
+dimensions = 128
+index_on_write = true

package/config/identity/default-purpose.md

@@ -0,0 +1 @@
+Help the user accomplish their goals efficiently.

package/config/identity/default-soul.md

@@ -0,0 +1,3 @@
+You are a helpful, direct assistant.
+Be concise. Be honest. If you don't know something, say so.
+When closing a task: confirm what was done, not just that you tried.

package/config/identity/orchestrator-purpose.md

@@ -0,0 +1 @@
+Route incoming jobs to the most appropriate agent based on job type, agent capabilities, and current load.

package/config/identity/orchestrator-soul.md

@@ -0,0 +1 @@
+You are the Nemoris orchestrator — a routing and coordination agent that decides which agent handles each job.

package/config/improvement-targets.toml

@@ -0,0 +1,15 @@
+[targets.workspace_health]
+job_id = "workspace-health"
+default_mode = "provider"
+default_model_override = "ollama/qwen3:8b"
+default_timeout_ms = 60000
+allowed_knobs = ["report_guidance", "retrieval_blend", "model_override"]
+recommended_variants = ["baseline", "focus_concrete", "retrieval_lexical_heavy", "retrieval_embedding_heavy", "report_model_bump"]
+
+[targets.memory_rollup]
+job_id = "memory-rollup"
+default_mode = "provider"
+default_model_override = "ollama/qwen3:8b"
+default_timeout_ms = 75000
+allowed_knobs = ["report_guidance", "retrieval_blend", "model_override"]
+recommended_variants = ["baseline", "focus_concrete", "retrieval_lexical_heavy", "retrieval_embedding_heavy", "report_model_bump"]

package/config/jobs/heartbeat-check.toml

@@ -0,0 +1,30 @@
+id = "heartbeat-check"
+trigger = "every:30m"
+task_type = "heartbeat"
+agent_id = "assistant"
+model_lane = "local_cheap"
+output_target = "inbox"
+idempotency_key = "heartbeat-check"
+
+[budget]
+max_tokens = 3000
+max_runtime_seconds = 20
+
+[retry]
+max_attempts = 1
+
+[stop]
+halt_on_policy_error = true
+halt_on_budget_exceeded = true
+
+[interaction_contract]
+ack_mode = "silent"
+progress_mode = "none"
+notify_on_done = false
+notify_on_error = true
+requires_pingback = false
+pingback_target = "scheduler_log"
+completion_signal = "heartbeat_ok"
+failure_signal = "heartbeat_error"
+handoff_format = "concise_status"
+completion_sections = ["status"]