From 6b5dddbd4cc6c845aba55510322dcfc87a85e966 Mon Sep 17 00:00:00 2001 From: mihirkernora Date: Mon, 30 Mar 2026 10:11:14 -0700 Subject: [PATCH 1/6] =?UTF-8?q?Add=20Nora=20=E2=80=94=20AI=20Work=20Intell?= =?UTF-8?q?igence=20power?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Nora captures coding sessions, extracts patterns and decisions, then feeds them back as steering context. Your AI agent gets smarter every session. - 9 MCP tools for searching patterns, decisions, bugs, and inline dashboard - 4 hooks: agentSpawn, stop, preToolUse, postToolUse - 3 auto-updated steering files read by Kiro on every prompt - 100% local, zero telemetry, BYOK (Anthropic/Gemini/Bedrock/Ollama) - Python 3.9+ compatible --- nora/POWER.md | 255 +++++++++++++++++++++++++++++ nora/icon.svg | 27 +++ nora/mcp.json | 10 ++ nora/steering/nora-antipatterns.md | 11 ++ nora/steering/nora-decisions.md | 12 ++ nora/steering/nora-patterns.md | 13 ++ 6 files changed, 328 insertions(+) create mode 100644 nora/POWER.md create mode 100644 nora/icon.svg create mode 100644 nora/mcp.json create mode 100644 nora/steering/nora-antipatterns.md create mode 100644 nora/steering/nora-decisions.md create mode 100644 nora/steering/nora-patterns.md diff --git a/nora/POWER.md b/nora/POWER.md new file mode 100644 index 0000000..176a633 --- /dev/null +++ b/nora/POWER.md @@ -0,0 +1,255 @@ +--- +name: "nora" +displayName: "Nora — AI Work Intelligence" +description: "Your AI gets smarter every session. Nora captures sessions, learns patterns, injects context, and evolves steering — all locally." +keywords: ["nora", "kernora", "patterns", "context", "memory", "intelligence", "learning", "steering", "session", "decisions", "bugs", "anti-patterns", "knowledge", "recall", "history"] +author: "Kernora AI" +--- + +# Nora — AI Work Intelligence + +Nora is your silent coding partner. She captures every session, extracts patterns, decisions, and anti-patterns, then feeds them back as context and steering. Your AI gets smarter every session. + +100% local. Zero bytes leave your machine. BYOK (Bring Your Own Key). + +## Onboarding + +### Step 1: Check Prerequisites + +Verify the following are installed: + +- **Python 3.9+** — Run `python3 --version` to confirm +- **git** — Run `git --version` to confirm + +If either is missing, halt setup and inform the user. + +### Step 2: Install Nora Engine + +Check if Nora is already installed by looking for `~/.kernora/app/daemon.py`. + +If Nora is NOT installed, run: + +```bash +git clone https://github.com/kernora-ai/nora.git /tmp/nora-install && bash /tmp/nora-install/install.sh && rm -rf /tmp/nora-install +``` + +This installs the engine to `~/.kernora/`, creates a virtual environment, initializes the database, starts the daemon and dashboard, and configures auto-start on login. + +If Nora IS already installed, skip to Step 3. + +### Step 3: Configure API Key (Optional) + +Nora works out of the box without any API key. Session capture, pattern extraction (Phase 1), hooks, MCP tools, and steering files all run locally with zero LLM calls. + +For deeper semantic analysis (Phase 2), Nora can optionally use an LLM. If the user wants to enable this, check if any of these environment variables are set: + +- `ANTHROPIC_API_KEY` +- `GEMINI_API_KEY` +- `AWS_PROFILE` (for Bedrock) + +If none are set, Nora still works — Phase 1 deterministic analysis extracts patterns, file changes, tool usage, and error signatures without any LLM. Phase 2 is a bonus, not a gate. + +To use local Ollama instead of a cloud API: edit `~/.kernora/config.toml` and set `provider = "ollama"`. + +Skip this step if you just want to get started. + +### Step 4: Install Kiro Hooks + +Copy `hooks.json` to `.kiro/hooks/` in the workspace. This registers all four hooks: + +```json +{ + "hooks": { + "agentSpawn": [ + { + "matcher": "", + "hooks": [ + { + "type": "command", + "command": "python3 ~/.kiro/hooks/kiro_agent_spawn.py", + "timeout": 5 + } + ] + } + ], + "stop": [ + { + "matcher": "", + "hooks": [ + { + "type": "command", + "command": "python3 ~/.kiro/hooks/kiro_stop.py", + "async": true + } + ] + } + ], + "preToolUse": [ + { + "matcher": "", + "hooks": [ + { + "type": "command", + "command": "python3 ~/.kiro/hooks/kiro_spec_shield.py", + "timeout": 3 + } + ] + } + ], + "postToolUse": [ + { + "matcher": "", + "hooks": [ + { + "type": "command", + "command": "python3 ~/.kiro/hooks/kiro_post_tool.py", + "timeout": 3 + } + ] + } + ] + } +} +``` + +The four hooks: + +- **agentSpawn** — checks daemon health, verifies steering freshness, auto-starts daemon if down +- **stop** — captures session transcript, sends to Nora daemon for analysis (async) +- **preToolUse** — validates tool invocations against danger patterns and learned anti-patterns +- **postToolUse** — checks tool output against known error signatures from past sessions + +### Step 5: Copy Hook Scripts + +Download hook scripts to `~/.kiro/hooks/`: + +```bash +mkdir -p ~/.kiro/hooks +for f in kiro_agent_spawn.py kiro_stop.py kiro_spec_shield.py kiro_post_tool.py steering_writer.py; do + [ ! -f "$HOME/.kiro/hooks/$f" ] && curl -sfL "https://raw.githubusercontent.com/kernora-ai/kiro-claw/main/hooks/$f" -o "$HOME/.kiro/hooks/$f" +done +chmod +x ~/.kiro/hooks/*.py +``` + +### Step 6: Generate Initial Steering + +Run the steering writer to generate initial steering files: + +```bash +python3 ~/.kiro/hooks/steering_writer.py +``` + +This creates `~/.kiro/steering/nora-patterns.md`, `nora-decisions.md`, and `nora-antipatterns.md`. These are read by Kiro automatically on every prompt. + +### Step 7: Verify Installation + +Confirm Nora is running: + +1. Check daemon: `ls ~/.kernora/daemon.sock` (should exist) +2. Check dashboard: `curl -sf http://localhost:2742` (should return HTML) +3. Check steering: `ls ~/.kiro/steering/nora-*.md` (should list 3 files) + +If all three pass, Nora is ready. Tell the user: "Nora is installed. Your sessions will be captured and analyzed automatically. Steering files update after each session." + +## Available MCP Server + +### nora + +**Connection:** Local stdio process at `~/.kernora/app/nora_mcp.py` + +Nora's MCP server provides access to your session intelligence database. All data stays local in `~/.kernora/echo.db`. + +**Tools (11):** + +- **nora_search** — Full-text search across patterns, decisions, bugs, and insights from past sessions. Required: `query` (string). +- **nora_patterns** — List effective coding patterns, optionally filtered by project. Optional: `project` (string), `min_effectiveness` (number, 0-1). +- **nora_decisions** — List architectural decisions recorded across sessions. Optional: `project` (string). +- **nora_bugs** — List known bugs with severity, file path, and fix code. Optional: `status` (open/resolved/all), `severity` (critical/high/medium/low). +- **nora_stats** — Dashboard stats: session count, insights, patterns, decisions, open bugs, total tokens. +- **nora_session** — Get full details for a specific session by ID. Required: `session_id` (string). +- **nora_scope_validation** — Validate that planned execution scope is focused and safe before multi-file edits. Required: `intent` (string). Optional: `files_to_touch` (string array). +- **nora_skills** — Fetch distilled methodology from your team's highest-quality sessions. +- **nora_dashboard** — Full intelligence dashboard inline: KPIs, top patterns, recent decisions, open bugs, recent sessions, knowledge domains. Say "show dashboard" or "Nora status". +- **nora_analyze_pending** — Get next unanalyzed session with Phase 1 metadata + condensed transcript + analysis prompt. No arguments needed. +- **nora_store_analysis** — Store your analysis of a session (called after nora_analyze_pending). Required: `session_id` (string), `analysis` (object). + +## When to Load Steering Files + +Nora generates three global steering files that Kiro reads automatically. They don't need explicit loading — they're always active. However, these are the contexts where each is most valuable: + +- Starting a new coding task → `nora-patterns.md` provides reusable patterns and playbooks +- Making architectural choices → `nora-decisions.md` provides past decisions and rationale +- About to modify code → `nora-antipatterns.md` warns about known mistakes and bugs + +## How Nora Works + +1. **You code normally.** Nora is silent during your session. +2. **Session ends.** The stop hook captures the transcript and spools it locally. +3. **Next session starts.** The agentSpawn hook detects pending sessions and nudges the agent. +4. **Agent analyzes (zero API key).** Kiro's built-in model reads Phase 1 metadata + condensed transcript via `nora_analyze_pending`, generates semantic analysis, and stores it via `nora_store_analysis`. No external API key needed. +5. **Knowledge accumulates.** Patterns, decisions, and bugs are stored in `~/.kernora/echo.db`. +6. **Steering evolves.** After each analysis, steering files regenerate with the latest intelligence. +7. **Every session is smarter.** Kiro reads the steering files. The MCP tools answer questions about past work. + +**Optional:** If you have an API key (Anthropic, Gemini, etc.), the daemon can also analyze sessions in the background for deeper extraction. But the agent-as-analyzer path works with zero keys. + +## Privacy + +Nora runs 100% locally: + +- Session transcripts stored in `~/.kernora/echo.db` on your machine +- Agent-as-analyzer uses Kiro's built-in model — no external API calls +- Optional deep analysis uses YOUR API key if configured +- Steering files live in `~/.kiro/steering/` on your machine +- Zero telemetry, zero cloud storage, zero data sharing + +## Dashboard + +Open http://localhost:2742 to see: + +- Session history with analysis summaries +- Pattern library with effectiveness scores +- Architectural decision log +- Bug tracker with severity and fix code +- Knowledge Intelligence Quotient (KIQ) — your accumulated engineering judgment + +## Configuration + +Edit `~/.kernora/config.toml`: + +```toml +[mode] +type = "byok" # your key, your machine + +[model] +provider = "anthropic" # or "bedrock", "gemini", "ollama" + +[analysis] +run_every_minutes = 60 # how often to analyze new sessions + +[dashboard] +port = 2742 # dashboard port +``` + +## Troubleshooting + +### Daemon not running +```bash +~/.kernora/venv/bin/python3 ~/.kernora/app/daemon.py & +``` + +### No steering files generated +Run manually: `python3 ~/.kiro/hooks/steering_writer.py` +If echo.db is empty, complete a few coding sessions first. + +### MCP server not connecting +Verify the server starts: `~/.kernora/venv/bin/python3 ~/.kernora/app/nora_mcp.py` +Check for missing dependencies: `~/.kernora/venv/bin/pip install mcp` + +## Resources + +- [GitHub: kernora-ai/nora](https://github.com/kernora-ai/nora) — Engine source +- [GitHub: kernora-ai/kiro-claw](https://github.com/kernora-ai/kiro-claw) — Kiro hooks source +- [GitHub: kernora-ai/claude-claw](https://github.com/kernora-ai/claude-claw) — Claude Code hooks +- [Dashboard](http://localhost:2742) — Local web UI +- [kernora.ai](https://kernora.ai) — Documentation and guides diff --git a/nora/icon.svg b/nora/icon.svg new file mode 100644 index 0000000..8c1e287 --- /dev/null +++ b/nora/icon.svg @@ -0,0 +1,27 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + NORA + diff --git a/nora/mcp.json b/nora/mcp.json new file mode 100644 index 0000000..7fdbc9f --- /dev/null +++ b/nora/mcp.json @@ -0,0 +1,10 @@ +{ + "mcpServers": { + "nora": { + "command": "python3", + "args": ["${HOME}/.kernora/app/nora_mcp.py"], + "env": {}, + "disabled": false + } + } +} diff --git a/nora/steering/nora-antipatterns.md b/nora/steering/nora-antipatterns.md new file mode 100644 index 0000000..235b7b3 --- /dev/null +++ b/nora/steering/nora-antipatterns.md @@ -0,0 +1,11 @@ +# Nora Anti-Patterns + +*This file is auto-updated by Nora after each session analysis.* +*Anti-patterns will appear here after 2-3 coding sessions.* + +## How Anti-Patterns Work + +Nora identifies mistakes, bugs, and approaches that failed during your sessions. These +become warnings that prevent your agent from repeating the same mistakes. + +Kiro reads this file automatically on every prompt. diff --git a/nora/steering/nora-decisions.md b/nora/steering/nora-decisions.md new file mode 100644 index 0000000..9659b8a --- /dev/null +++ b/nora/steering/nora-decisions.md @@ -0,0 +1,12 @@ +# Nora Decisions + +*This file is auto-updated by Nora after each session analysis.* +*Architectural decisions will appear here after 2-3 coding sessions.* + +## How Decisions Work + +Nora records architectural and design decisions made during your sessions — technology +choices, trade-off rationale, and structural commitments. This prevents your agent from +relitigating decisions you've already made. + +Kiro reads this file automatically on every prompt. diff --git a/nora/steering/nora-patterns.md b/nora/steering/nora-patterns.md new file mode 100644 index 0000000..405017e --- /dev/null +++ b/nora/steering/nora-patterns.md @@ -0,0 +1,13 @@ +# Nora Patterns + +*This file is auto-updated by Nora after each session analysis.* +*Patterns will appear here after 2-3 coding sessions.* + +## How Patterns Work + +Nora extracts effective coding patterns from your sessions — approaches that worked well, +shortcuts that saved time, and techniques worth repeating. Each pattern includes an +effectiveness score (0-1) based on how reliably it produces good outcomes. + +Kiro reads this file automatically on every prompt, so these patterns inform your agent's +behavior without you needing to do anything. From 0009b594dc12ec21356b0982c1dd928af5230b14 Mon Sep 17 00:00:00 2001 From: mihir-kernora Date: Sun, 5 Apr 2026 15:04:13 -0700 Subject: [PATCH 2/6] =?UTF-8?q?Update=20Nora=20power=20to=20v2.1.0=20?= =?UTF-8?q?=E2=80=94=2018=20MCP=20tools,=20AI=20Leverage=20Score,=20local?= =?UTF-8?q?=20LLM?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- nora/POWER.md | 267 +++++++++++++++++--------------------------------- 1 file changed, 88 insertions(+), 179 deletions(-) diff --git a/nora/POWER.md b/nora/POWER.md index 176a633..b9519d0 100644 --- a/nora/POWER.md +++ b/nora/POWER.md @@ -1,16 +1,16 @@ --- name: "nora" displayName: "Nora — AI Work Intelligence" -description: "Your AI gets smarter every session. Nora captures sessions, learns patterns, injects context, and evolves steering — all locally." -keywords: ["nora", "kernora", "patterns", "context", "memory", "intelligence", "learning", "steering", "session", "decisions", "bugs", "anti-patterns", "knowledge", "recall", "history"] +description: "Your AI gets smarter every session. Nora captures sessions, learns patterns, injects context, and compounds your AI Leverage — all locally." +keywords: ["nora", "kernora", "patterns", "context", "memory", "intelligence", "learning", "steering", "session", "decisions", "bugs", "anti-patterns", "knowledge", "leverage", "coaching"] author: "Kernora AI" --- # Nora — AI Work Intelligence -Nora is your silent coding partner. She captures every session, extracts patterns, decisions, and anti-patterns, then feeds them back as context and steering. Your AI gets smarter every session. +Nora is your silent coding partner. She captures every session, extracts patterns, decisions, and anti-patterns, then feeds them back as context and steering. Your AI Leverage Score compounds toward 5.0x as Nora learns your patterns. -100% local. Zero bytes leave your machine. BYOK (Bring Your Own Key). +100% local. Zero bytes leave your machine. No API key required on Mac. ## Onboarding @@ -23,195 +23,104 @@ Verify the following are installed: If either is missing, halt setup and inform the user. -### Step 2: Install Nora Engine +### Step 2: Install Nora -Check if Nora is already installed by looking for `~/.kernora/app/daemon.py`. - -If Nora is NOT installed, run: +Nora bootstraps automatically when installed as a Kiro Power. +For manual install: ```bash git clone https://github.com/kernora-ai/nora.git /tmp/nora-install && bash /tmp/nora-install/install.sh && rm -rf /tmp/nora-install ``` -This installs the engine to `~/.kernora/`, creates a virtual environment, initializes the database, starts the daemon and dashboard, and configures auto-start on login. - -If Nora IS already installed, skip to Step 3. - -### Step 3: Configure API Key (Optional) +### Step 3: Configure LLM (Optional) -Nora works out of the box without any API key. Session capture, pattern extraction (Phase 1), hooks, MCP tools, and steering files all run locally with zero LLM calls. - -For deeper semantic analysis (Phase 2), Nora can optionally use an LLM. If the user wants to enable this, check if any of these environment variables are set: +Nora works out of the box with no API key on Mac (Apple FoundationModels on macOS 26+, MLX-LM on macOS 14+). +For cloud analysis, set any of these environment variables: - `ANTHROPIC_API_KEY` - `GEMINI_API_KEY` +- `OPENAI_API_KEY` - `AWS_PROFILE` (for Bedrock) -If none are set, Nora still works — Phase 1 deterministic analysis extracts patterns, file changes, tool usage, and error signatures without any LLM. Phase 2 is a bonus, not a gate. - -To use local Ollama instead of a cloud API: edit `~/.kernora/config.toml` and set `provider = "ollama"`. - -Skip this step if you just want to get started. - -### Step 4: Install Kiro Hooks - -Copy `hooks.json` to `.kiro/hooks/` in the workspace. This registers all four hooks: - -```json -{ - "hooks": { - "agentSpawn": [ - { - "matcher": "", - "hooks": [ - { - "type": "command", - "command": "python3 ~/.kiro/hooks/kiro_agent_spawn.py", - "timeout": 5 - } - ] - } - ], - "stop": [ - { - "matcher": "", - "hooks": [ - { - "type": "command", - "command": "python3 ~/.kiro/hooks/kiro_stop.py", - "async": true - } - ] - } - ], - "preToolUse": [ - { - "matcher": "", - "hooks": [ - { - "type": "command", - "command": "python3 ~/.kiro/hooks/kiro_spec_shield.py", - "timeout": 3 - } - ] - } - ], - "postToolUse": [ - { - "matcher": "", - "hooks": [ - { - "type": "command", - "command": "python3 ~/.kiro/hooks/kiro_post_tool.py", - "timeout": 3 - } - ] - } - ] - } -} -``` - -The four hooks: - -- **agentSpawn** — checks daemon health, verifies steering freshness, auto-starts daemon if down -- **stop** — captures session transcript, sends to Nora daemon for analysis (async) -- **preToolUse** — validates tool invocations against danger patterns and learned anti-patterns -- **postToolUse** — checks tool output against known error signatures from past sessions - -### Step 5: Copy Hook Scripts - -Download hook scripts to `~/.kiro/hooks/`: - -```bash -mkdir -p ~/.kiro/hooks -for f in kiro_agent_spawn.py kiro_stop.py kiro_spec_shield.py kiro_post_tool.py steering_writer.py; do - [ ! -f "$HOME/.kiro/hooks/$f" ] && curl -sfL "https://raw.githubusercontent.com/kernora-ai/kiro-claw/main/hooks/$f" -o "$HOME/.kiro/hooks/$f" -done -chmod +x ~/.kiro/hooks/*.py -``` - -### Step 6: Generate Initial Steering - -Run the steering writer to generate initial steering files: - -```bash -python3 ~/.kiro/hooks/steering_writer.py -``` - -This creates `~/.kiro/steering/nora-patterns.md`, `nora-decisions.md`, and `nora-antipatterns.md`. These are read by Kiro automatically on every prompt. - -### Step 7: Verify Installation +Provider priority: IDE LLM → Apple FoundationModels → MLX-LM → BYOK API keys → Ollama. -Confirm Nora is running: +### Step 4: Verify Installation -1. Check daemon: `ls ~/.kernora/daemon.sock` (should exist) -2. Check dashboard: `curl -sf http://localhost:2742` (should return HTML) -3. Check steering: `ls ~/.kiro/steering/nora-*.md` (should list 3 files) - -If all three pass, Nora is ready. Tell the user: "Nora is installed. Your sessions will be captured and analyzed automatically. Steering files update after each session." +1. Check dashboard: `curl -sf http://localhost:2742/health` (should return JSON with `"status":"ok"`) +2. Check steering: `ls ~/.kiro/steering/nora-*.md` (should list 3 files) ## Available MCP Server ### nora -**Connection:** Local stdio process at `~/.kernora/app/nora_mcp.py` - -Nora's MCP server provides access to your session intelligence database. All data stays local in `~/.kernora/echo.db`. - -**Tools (11):** +**Connection:** Local stdio process + +Nora's MCP server provides 18 tools for querying your session intelligence. All data stays local in `~/.kernora/echo.db`. + +**Tools (18):** + +- **nora_search** — Full-text search across patterns, decisions, bugs, and insights +- **nora_patterns** — List effective coding patterns, optionally filtered by project +- **nora_decisions** — List architectural decisions recorded across sessions +- **nora_bugs** — List known bugs with severity, file path, and fix code +- **nora_stats** — Dashboard stats: sessions, insights, AI Leverage Score +- **nora_session** — Get full details for a specific session by ID +- **nora_scope_validation** — Validate execution scope before multi-file edits +- **nora_skills** — Fetch distilled methodology from your best sessions +- **nora_scan** — Seed database from git history +- **nora_pe_review** — Principal Engineer 4-tier code audit +- **nora_coe** — Blameless root cause investigation (5 whys) +- **nora_coe_product** — Product COE — why was this built wrong +- **nora_retro** — Engineering retrospective with git velocity +- **nora_sofac** — Factory health status +- **nora_inventory** — Feature audit: SHIP/POLISH/WIRE/BLOCKER +- **nora_coach** — AI leverage coaching +- **nora_onboard** — Onboard a new developer +- **nora_help** — List all tools -- **nora_search** — Full-text search across patterns, decisions, bugs, and insights from past sessions. Required: `query` (string). -- **nora_patterns** — List effective coding patterns, optionally filtered by project. Optional: `project` (string), `min_effectiveness` (number, 0-1). -- **nora_decisions** — List architectural decisions recorded across sessions. Optional: `project` (string). -- **nora_bugs** — List known bugs with severity, file path, and fix code. Optional: `status` (open/resolved/all), `severity` (critical/high/medium/low). -- **nora_stats** — Dashboard stats: session count, insights, patterns, decisions, open bugs, total tokens. -- **nora_session** — Get full details for a specific session by ID. Required: `session_id` (string). -- **nora_scope_validation** — Validate that planned execution scope is focused and safe before multi-file edits. Required: `intent` (string). Optional: `files_to_touch` (string array). -- **nora_skills** — Fetch distilled methodology from your team's highest-quality sessions. -- **nora_dashboard** — Full intelligence dashboard inline: KPIs, top patterns, recent decisions, open bugs, recent sessions, knowledge domains. Say "show dashboard" or "Nora status". -- **nora_analyze_pending** — Get next unanalyzed session with Phase 1 metadata + condensed transcript + analysis prompt. No arguments needed. -- **nora_store_analysis** — Store your analysis of a session (called after nora_analyze_pending). Required: `session_id` (string), `analysis` (object). - -## When to Load Steering Files +## How Nora Works -Nora generates three global steering files that Kiro reads automatically. They don't need explicit loading — they're always active. However, these are the contexts where each is most valuable: +1. **You code normally.** Nora is silent during your session. +2. **Session ends.** Hooks capture the transcript locally. +3. **Nora analyzes.** Extracts patterns, decisions, bugs, and your AI Leverage Score. +4. **Steering evolves.** Steering files regenerate with the latest intelligence. +5. **Next session is smarter.** Context from past sessions is injected into your prompts. -- Starting a new coding task → `nora-patterns.md` provides reusable patterns and playbooks -- Making architectural choices → `nora-decisions.md` provides past decisions and rationale -- About to modify code → `nora-antipatterns.md` warns about known mistakes and bugs +## AI Leverage Score -## How Nora Works +A composite metric measuring your AI effectiveness: -1. **You code normally.** Nora is silent during your session. -2. **Session ends.** The stop hook captures the transcript and spools it locally. -3. **Next session starts.** The agentSpawn hook detects pending sessions and nudges the agent. -4. **Agent analyzes (zero API key).** Kiro's built-in model reads Phase 1 metadata + condensed transcript via `nora_analyze_pending`, generates semantic analysis, and stores it via `nora_store_analysis`. No external API key needed. -5. **Knowledge accumulates.** Patterns, decisions, and bugs are stored in `~/.kernora/echo.db`. -6. **Steering evolves.** After each analysis, steering files regenerate with the latest intelligence. -7. **Every session is smarter.** Kiro reads the steering files. The MCP tools answer questions about past work. +| Score | Label | What it means | +|-------|-------|--------------| +| 1.0–2.0 | Early | AI isn't helping much yet | +| 2.0–3.0 | Developing | Getting value, room to grow | +| 3.0–4.0 | Strong | Measurably effective AI usage | +| 4.0–5.0 | Excellent | Elite AI collaboration | -**Optional:** If you have an API key (Anthropic, Gemini, etc.), the daemon can also analyze sessions in the background for deeper extraction. But the agent-as-analyzer path works with zero keys. +Export your score as a shareable certificate from the Coach tab in the dashboard. ## Privacy -Nora runs 100% locally: - - Session transcripts stored in `~/.kernora/echo.db` on your machine -- Agent-as-analyzer uses Kiro's built-in model — no external API calls -- Optional deep analysis uses YOUR API key if configured -- Steering files live in `~/.kiro/steering/` on your machine +- Local LLM analysis via Apple FoundationModels or MLX-LM — zero network calls +- Optional cloud analysis uses YOUR API key if configured - Zero telemetry, zero cloud storage, zero data sharing ## Dashboard Open http://localhost:2742 to see: -- Session history with analysis summaries -- Pattern library with effectiveness scores -- Architectural decision log -- Bug tracker with severity and fix code -- Knowledge Intelligence Quotient (KIQ) — your accumulated engineering judgment +| Tab | What it shows | +|-----|--------------| +| **Home** | AI Leverage Score, loop health, top projects, rule suggestions | +| **Projects** | Per-project AI metrics, patterns, decisions, bugs | +| **Activity** | Session history with outcome indicators | +| **Coach** | AI Leverage sparkline, coaching notes, decision patterns, certificate | +| **Knowledge** | Best practices, playbooks, anti-patterns | +| **Memory** | Context injection feed, steering file viewer | +| **Decisions** | Searchable architectural decisions | +| **Bugs** | Bug inventory with severity, fix suggestions, mark resolved | +| **Settings** | LLM provider config, local AI status | ## Configuration @@ -219,37 +128,37 @@ Edit `~/.kernora/config.toml`: ```toml [mode] -type = "byok" # your key, your machine +type = "byok" # your data stays on your machine [model] -provider = "anthropic" # or "bedrock", "gemini", "ollama" - -[analysis] -run_every_minutes = 60 # how often to analyze new sessions +provider = "auto" # tries IDE → local → BYOK → Ollama [dashboard] -port = 2742 # dashboard port +port = 2742 ``` ## Troubleshooting -### Daemon not running -```bash -~/.kernora/venv/bin/python3 ~/.kernora/app/daemon.py & -``` +**Dashboard not loading?** Run `python3 ~/.kernora/app/dashboard.py` and check for errors. Most common: missing Flask dependency — run `pip3 install flask`. -### No steering files generated -Run manually: `python3 ~/.kiro/hooks/steering_writer.py` -If echo.db is empty, complete a few coding sessions first. +**Steering files empty?** Steering regenerates after the first analyzed session. Run a coding session, then check `~/.kiro/steering/nora-*.md`. -### MCP server not connecting -Verify the server starts: `~/.kernora/venv/bin/python3 ~/.kernora/app/nora_mcp.py` -Check for missing dependencies: `~/.kernora/venv/bin/pip install mcp` +**Analysis not running?** Check the Settings tab in the dashboard. Verify your LLM provider is connected (green indicator). On Mac with no API key, ensure macOS 26+ for Apple FoundationModels or macOS 14+ for MLX-LM. ## Resources -- [GitHub: kernora-ai/nora](https://github.com/kernora-ai/nora) — Engine source -- [GitHub: kernora-ai/kiro-claw](https://github.com/kernora-ai/kiro-claw) — Kiro hooks source -- [GitHub: kernora-ai/claude-claw](https://github.com/kernora-ai/claude-claw) — Claude Code hooks -- [Dashboard](http://localhost:2742) — Local web UI -- [kernora.ai](https://kernora.ai) — Documentation and guides +- [GitHub: kernora-ai/nora](https://github.com/kernora-ai/nora) +- [Dashboard](http://localhost:2742) +- [kernora.ai](https://kernora.ai) + +## License and support + +This power is licensed under Elastic License 2.0 (Elastic-2.0). + +**Privacy Policy** + +https://kernora.ai/privacy + +**Support** + +https://github.com/kernora-ai/nora/issues | hello@kernora.ai From 4ebdb87c3ce650304fb3362b3884c7d2b5c79fac Mon Sep 17 00:00:00 2001 From: mihir-kernora Date: Sun, 5 Apr 2026 15:05:04 -0700 Subject: [PATCH 3/6] =?UTF-8?q?Clean=20up=20mcp.json=20=E2=80=94=20remove?= =?UTF-8?q?=20disabled=20field?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- nora/mcp.json | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/nora/mcp.json b/nora/mcp.json index 7fdbc9f..69a964d 100644 --- a/nora/mcp.json +++ b/nora/mcp.json @@ -3,8 +3,7 @@ "nora": { "command": "python3", "args": ["${HOME}/.kernora/app/nora_mcp.py"], - "env": {}, - "disabled": false + "env": {} } } } From 4a6656b31b0bf821734ccdc89dc143a560490847 Mon Sep 17 00:00:00 2001 From: mihir-kernora Date: Sun, 5 Apr 2026 15:05:52 -0700 Subject: [PATCH 4/6] Update nora-patterns.md --- nora/steering/nora-patterns.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/nora/steering/nora-patterns.md b/nora/steering/nora-patterns.md index 405017e..a8be366 100644 --- a/nora/steering/nora-patterns.md +++ b/nora/steering/nora-patterns.md @@ -1,13 +1,15 @@ -# Nora Patterns +# Nora — Effective Patterns -*This file is auto-updated by Nora after each session analysis.* -*Patterns will appear here after 2-3 coding sessions.* +> Auto-updated after session analysis. Activates automatically in Kiro. -## How Patterns Work +Patterns are extracted from your coding sessions and ranked by effectiveness score (0–1.0). +Higher scores mean the pattern is frequently used and consistently produces good outcomes. -Nora extracts effective coding patterns from your sessions — approaches that worked well, -shortcuts that saved time, and techniques worth repeating. Each pattern includes an -effectiveness score (0-1) based on how reliably it produces good outcomes. +## How patterns work -Kiro reads this file automatically on every prompt, so these patterns inform your agent's -behavior without you needing to do anything. +1. Nora observes tool usage and code changes during each session +2. After analysis, recurring effective approaches are extracted as patterns +3. Patterns are injected into future sessions when relevant context matches +4. Effectiveness scores update as Nora observes whether injected patterns are adopted + +*This file populates after your first analyzed session.* From fd6438ab5fb38046f3ce8836317ab8bf3cb05127 Mon Sep 17 00:00:00 2001 From: mihir-kernora Date: Sun, 5 Apr 2026 15:06:23 -0700 Subject: [PATCH 5/6] Update nora-decisions.md --- nora/steering/nora-decisions.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/nora/steering/nora-decisions.md b/nora/steering/nora-decisions.md index 9659b8a..1ef2f97 100644 --- a/nora/steering/nora-decisions.md +++ b/nora/steering/nora-decisions.md @@ -1,12 +1,15 @@ -# Nora Decisions +# Nora — Architectural Decisions -*This file is auto-updated by Nora after each session analysis.* -*Architectural decisions will appear here after 2-3 coding sessions.* +> Auto-updated after session analysis. Activates automatically in Kiro. -## How Decisions Work +Decisions record what was chosen, why, and what alternatives were considered. +Nora extracts these from session transcripts so your team never re-debates settled questions. -Nora records architectural and design decisions made during your sessions — technology -choices, trade-off rationale, and structural commitments. This prevents your agent from -relitigating decisions you've already made. +## How decisions work -Kiro reads this file automatically on every prompt. +1. Nora identifies architectural and design choices from session transcripts +2. Each decision includes rationale, alternatives considered, and affected files +3. Decisions are injected into future sessions when a similar choice arises +4. Prevents the same debate from recurring across sessions or team members + +*This file populates after your first analyzed session.* From 2fab636e6431264809af97bbeb9646d9807e69da Mon Sep 17 00:00:00 2001 From: mihir-kernora Date: Sun, 5 Apr 2026 15:06:48 -0700 Subject: [PATCH 6/6] Update nora-antipatterns.md --- nora/steering/nora-antipatterns.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/nora/steering/nora-antipatterns.md b/nora/steering/nora-antipatterns.md index 235b7b3..cccef08 100644 --- a/nora/steering/nora-antipatterns.md +++ b/nora/steering/nora-antipatterns.md @@ -1,11 +1,15 @@ -# Nora Anti-Patterns +# Nora — Anti-Patterns -*This file is auto-updated by Nora after each session analysis.* -*Anti-patterns will appear here after 2-3 coding sessions.* +> Auto-updated after session analysis. Activates automatically in Kiro. -## How Anti-Patterns Work +Anti-patterns are mistakes, failed approaches, and bugs that Nora has observed. +They act as guardrails — Nora warns you before you repeat a known mistake. -Nora identifies mistakes, bugs, and approaches that failed during your sessions. These -become warnings that prevent your agent from repeating the same mistakes. +## How anti-patterns work -Kiro reads this file automatically on every prompt. +1. Nora identifies bugs, failed approaches, and error patterns from sessions +2. Each anti-pattern includes the error signature, affected files, and suggested fix +3. Anti-patterns are injected as warnings when Nora detects you're about to repeat one +4. Mark anti-patterns as resolved in the Bugs tab when the underlying issue is fixed + +*This file populates after your first analyzed session.*