diff --git a/CLAUDE.md b/CLAUDE.md
index ce23c14..4fa4517 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,5 +1,5 @@
 <coding_guidelines>
-# Vox — Personal Terminal Agent
+# Vox — Self-Learning Terminal Agent
 
 ## Build & Test
 ```bash
@@ -15,9 +15,12 @@ uv sync --extra voice
 ```
 
 ## Architecture
-- `src/vox/cli.py` — Subcommand dispatcher: REPL, listen, speak, agent, config
-- `src/vox/engine.py` — Ollama API client, response cleaning, general LLM queries
+- `src/vox/cli.py` — Subcommand dispatcher: REPL, listen, speak, agent, learn, config
+- `src/vox/engine.py` — Ollama API client, context-enriched prompts, response cleaning
 - `src/vox/config.py` — TOML config (~/.config/vox/config.toml) with env overrides
+- `src/vox/safety.py` — Dangerous command detection and non-shell response filtering
+- `src/vox/executor.py` — Command execution and clipboard utilities
+- `src/vox/knowledge.py` — SQLite self-learning store (6 context layers)
 - `src/vox/voice/recorder.py` — Microphone capture via sounddevice
 - `src/vox/voice/asr.py` — Speech-to-text (Parakeet 0.6B via mlx-audio)
 - `src/vox/voice/tts.py` — Text-to-speech (Kokoro 82M via mlx-audio)
@@ -25,8 +28,16 @@ uv sync --extra voice
 - `src/vox/agents/router.py` — Auto-route tasks to best installed agent via LLM
 - `src/vox/agents/{claude,codex,gemini,amp,droid}.py` — Headless agent wrappers
 - `scripts/finetune/` — Dataset building and LoRA fine-tuning pipeline
-- `install.sh` / `uninstall.sh` — curl-installable scripts
-- `docs/index.html` — GitHub Pages landing
+
+## Self-Learning (knowledge.py)
+SQLite store at ~/.config/vox/knowledge.db with 6 layers:
+1. Command patterns — validated NL-to-shell mappings (FTS5 indexed)
+2. User corrections — rejected commands + corrected versions
+3. Error patterns — commands that failed + error output
+5. Agent learnings — which agent handles which task best
+6. Session context — directory-aware recent commands
+
+After 3+ successful uses, a pattern is served from cache (skipping LLM).
 
 ## Backend
 Ollama API (local inference, no cloud). Default model: qwen2.5-coder:0.5b.
@@ -37,18 +48,19 @@ Agents: auto-discovers claude, codex, gemini, amp, droid in PATH.
 ```
 vox                        # Interactive REPL
 vox "find large files"     # Single NL-to-shell
-vox listen                 # Voice → shell command
+vox listen                 # Voice -> shell command
 vox speak "hello"          # Text-to-speech
 vox agent "fix tests"      # Delegate to AI agent (auto-routed)
 vox agent --list           # Show detected agents
-vox agent --use claude "x" # Force specific agent
+vox learn show             # Show top learned patterns
+vox learn stats            # Knowledge store statistics
+vox learn export -f p.json # Export patterns
 vox config init            # Create config template
-vox config show            # Display current config
 ```
 
 ## Conventions
 - Python 3.10+, ruff for lint/format
-- Keep core dependencies minimal (httpx, rich)
+- Keep core dependencies minimal (httpx, rich, sqlite3)
 - Voice/finetune deps are optional extras
 - All shell commands single-line, no heredocs
 </coding_guidelines>
diff --git a/README.md b/README.md
index 6967386..a9c9ff2 100644
--- a/README.md
+++ b/README.md
@@ -13,7 +13,7 @@ vox > find all python files bigger than 1MB
 ## Install
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/aryateja2106/vox/main/install.sh | bash
+curl -fsSL https://raw.githubusercontent.com/nl2shell/vox/main/install.sh | bash
 ```
 
 **Requirements:** Python 3.9+, [Ollama](https://ollama.ai) for local inference.
@@ -21,7 +21,7 @@ curl -fsSL https://raw.githubusercontent.com/aryateja2106/vox/main/install.sh |
 ## Uninstall
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/aryateja2106/vox/main/uninstall.sh | bash
+curl -fsSL https://raw.githubusercontent.com/nl2shell/vox/main/uninstall.sh | bash
 ```
 
 ## Usage
@@ -106,7 +106,7 @@ Vox is a step toward a world where the terminal understands you — not the othe
 
 ## Model
 
-Vox is powered by [NL2Shell](https://github.com/aryateja2106/nl2shell), a fine-tuned Qwen3.5-0.8B model trained specifically for natural language to shell command translation.
+Vox is powered by [NL2Shell](https://github.com/nl2shell/nl2shell), a fine-tuned Qwen3.5-0.8B model trained specifically for natural language to shell command translation.
 
 - **Parameters:** ~859M (runs on CPU, no GPU needed)
 - **Training data:** 12,000+ deduplicated NL→bash pairs including 960+ expert-curated commands
@@ -118,7 +118,7 @@ You can also use any other Ollama model: `vox --model llama3.2`
 ## Contributing
 
 ```bash
-git clone https://github.com/aryateja2106/vox.git
+git clone https://github.com/nl2shell/vox.git
 cd vox
 uv sync
 uv run python -m vox
diff --git a/docs/index.html b/docs/index.html
index 77a842a..f9fc688 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -300,7 +300,7 @@
     <a href="#examples">Examples</a>
     <a href="#why">Why Vox</a>
   </div>
-  <a href="https://github.com/aryateja2106/vox" class="nav-github" target="_blank" rel="noopener">
+  <a href="https://github.com/nl2shell/vox" class="nav-github" target="_blank" rel="noopener">
     &#9733; Star on GitHub
   </a>
 </nav>
@@ -331,11 +331,11 @@ <h1>Talk to your terminal.</h1>
       <button class="tab-btn" onclick="switchTab('uninstall', this)">Uninstall</button>
     </div>
     <div id="tab-install" class="tab-content active">
-      <code>curl -fsSL https://raw.githubusercontent.com/aryateja2106/vox/main/install.sh | bash</code>
+      <code>curl -fsSL https://raw.githubusercontent.com/nl2shell/vox/main/install.sh | bash</code>
       <button class="copy-btn" onclick="copyCmd('install')">Copy</button>
     </div>
     <div id="tab-uninstall" class="tab-content">
-      <code>curl -fsSL https://raw.githubusercontent.com/aryateja2106/vox/main/uninstall.sh | bash</code>
+      <code>curl -fsSL https://raw.githubusercontent.com/nl2shell/vox/main/uninstall.sh | bash</code>
       <button class="copy-btn" onclick="copyCmd('uninstall')">Copy</button>
     </div>
   </div>
@@ -481,7 +481,7 @@ <h2>Three ways to use it.</h2>
   <h2>Your terminal, finally fluent.</h2>
   <p>Install in under 10 seconds. No setup. No config. No excuses.</p>
   <div class="btn-group">
-    <a href="https://github.com/aryateja2106/vox" class="btn-primary" target="_blank" rel="noopener">
+    <a href="https://github.com/nl2shell/vox" class="btn-primary" target="_blank" rel="noopener">
       &#9733; Star on GitHub
     </a>
     <a href="#" class="btn-secondary" onclick="document.querySelector('.install-box').scrollIntoView({behavior:'smooth'});return false;">
@@ -493,17 +493,17 @@ <h2>Your terminal, finally fluent.</h2>
 <!-- FOOTER -->
 <footer>
   <p>
-    <a href="https://github.com/aryateja2106/vox" target="_blank" rel="noopener">github.com/aryateja2106/vox</a>
+    <a href="https://github.com/nl2shell/vox" target="_blank" rel="noopener">github.com/nl2shell/vox</a>
     &nbsp;&mdash;&nbsp;
-    Built by <a href="https://github.com/aryateja2106" target="_blank" rel="noopener">Arya Teja</a>.
+    Built by <a href="https://github.com/nl2shell" target="_blank" rel="noopener">Arya Teja</a>.
     Powered by <a href="https://huggingface.co/AryaYT/nl2shell-0.8b" target="_blank" rel="noopener">NL2Shell</a>.
   </p>
 </footer>
 
 <script>
   const cmds = {
-    install:   'curl -fsSL https://raw.githubusercontent.com/aryateja2106/vox/main/install.sh | bash',
-    uninstall: 'curl -fsSL https://raw.githubusercontent.com/aryateja2106/vox/main/uninstall.sh | bash'
+    install:   'curl -fsSL https://raw.githubusercontent.com/nl2shell/vox/main/install.sh | bash',
+    uninstall: 'curl -fsSL https://raw.githubusercontent.com/nl2shell/vox/main/uninstall.sh | bash'
   };
 
   function switchTab(name, btn) {
diff --git a/install.sh b/install.sh
index 002ae1c..3ec7a72 100755
--- a/install.sh
+++ b/install.sh
@@ -33,7 +33,7 @@ fi
 echo -e "  ${GREEN}✓${NC} Python $PY_VERSION"
 
 # ── Install vox ──────────────────────────────────────────────────────────────
-REPO="https://github.com/aryateja2106/vox.git"
+REPO="https://github.com/nl2shell/vox.git"
 
 if command -v pipx &>/dev/null; then
     echo -e "  ${DIM}Installing with pipx...${NC}"
diff --git a/pyproject.toml b/pyproject.toml
index 22e57db..9d13d01 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,7 +1,7 @@
 [project]
 name = "vox-shell"
-version = "0.3.0"
-description = "Personal terminal agent. Voice, AI agents, and natural language to shell — all local."
+version = "0.4.0"
+description = "Self-learning terminal agent. Voice, AI agents, and natural language to shell — all local."
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.10"
@@ -44,9 +44,9 @@ prerelease = "if-necessary-or-explicit"
 vox = "vox.cli:main"
 
 [project.urls]
-Homepage = "https://aryateja2106.github.io/vox"
-Repository = "https://github.com/aryateja2106/vox"
-Issues = "https://github.com/aryateja2106/vox/issues"
+Homepage = "https://nl2shell.github.io/vox"
+Repository = "https://github.com/nl2shell/vox"
+Issues = "https://github.com/nl2shell/vox/issues"
 
 [build-system]
 requires = ["hatchling"]
@@ -75,4 +75,5 @@ allowed-unresolved-imports = [
 [dependency-groups]
 dev = [
     "pytest>=8.4.2",
+    "ruff>=0.15.9",
 ]
diff --git a/src/vox/__init__.py b/src/vox/__init__.py
index 0a10e43..c79e940 100644
--- a/src/vox/__init__.py
+++ b/src/vox/__init__.py
@@ -1,3 +1,3 @@
 """Vox — Talk to your terminal."""
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"
diff --git a/src/vox/cli.py b/src/vox/cli.py
index 4ab08e7..6c4b53e 100644
--- a/src/vox/cli.py
+++ b/src/vox/cli.py
@@ -5,10 +5,7 @@
 import argparse
 import atexit
 import os
-import re
 import readline
-import shlex
-import subprocess
 import sys
 from pathlib import Path
 
@@ -18,6 +15,16 @@
 
 from vox import __version__
 from vox.config import CONFIG_FILE, VoxConfig, init_config, load_config
+from vox.executor import copy_to_clipboard, execute_command
+from vox.safety import is_dangerous, looks_like_shell
+
+# Re-export for backward compatibility (tests import these from vox.cli)
+__all__ = [
+    "copy_to_clipboard",
+    "execute_command",
+    "is_dangerous",
+    "looks_like_shell",
+]
 
 HISTORY_FILE = Path.home() / ".vox_history"
 
@@ -35,43 +42,6 @@ def setup_history() -> None:
 
 console = Console()
 
-DANGEROUS_PATTERNS = [
-    r"\brm\s+.*-\w*[rf]\w*",
-    r"\brm\s+-\w*R",
-    r"\bsudo\b",
-    r"\bdd\b\s+if=",
-    r"\bmkfs\b",
-    r"\bshred\b",
-    r"\bwipefs\b",
-    r"\b:\(\)\s*\{",
-    r"\bchmod\s+777\b",
-    r">\s*/dev/sd[a-z]",
-    r"\bsystemctl\s+(stop|disable|mask)\b",
-    r"\bkillall\b",
-    r"\breboot\b",
-    r"\bshutdown\b",
-    r"\bpoweroff\b",
-]
-
-NON_SHELL_PATTERNS = [
-    r"^\s*import\s+",
-    r"^\s*from\s+\w+\s+import\b",
-    r"^\s*def\s+\w+\(",
-    r"^\s*class\s+\w+",
-    r"^\s*<\?php",
-    r"^\s*<html",
-    r"^\s*\{\"",
-]
-
-
-def is_dangerous(cmd: str) -> bool:
-    return any(re.search(p, cmd, re.IGNORECASE) for p in DANGEROUS_PATTERNS)
-
-
-def looks_like_shell(cmd: str) -> bool:
-    first_line = cmd.split("\n")[0] if cmd else ""
-    return not any(re.search(p, first_line) for p in NON_SHELL_PATTERNS)
-
 
 def print_command(cmd: str, dangerous: bool = False) -> None:
     console.print()
@@ -85,47 +55,27 @@ def print_command(cmd: str, dangerous: bool = False) -> None:
         console.print("  [yellow]Note: multi-line command.[/yellow]")
 
 
-def execute_command(cmd: str) -> int:
-    needs_shell = any(c in cmd for c in "|;&$`()<>")
-    try:
-        if needs_shell:
-            result = subprocess.run(cmd, shell=True, check=False)
-        else:
-            result = subprocess.run(shlex.split(cmd), check=False)
-        return result.returncode
-    except ValueError:
-        result = subprocess.run(cmd, shell=True, check=False)
-        return result.returncode
-    except FileNotFoundError:
-        console.print(f"  [red]Command not found: {cmd.split()[0]}[/red]")
-        return 127
-    except KeyboardInterrupt:
-        console.print("\n[dim][interrupted][/dim]")
-        return 130
+def _get_knowledge(cfg: VoxConfig):
+    """Get the knowledge store singleton (lazy init)."""
+    if not cfg.learning.enabled:
+        return None
+    from pathlib import Path
 
+    from vox.knowledge import KnowledgeStore
 
-def copy_to_clipboard(text: str) -> bool:
-    try:
-        if sys.platform == "darwin":
-            subprocess.run(["pbcopy"], input=text.encode(), check=True)
-        else:
-            subprocess.run(
-                ["xclip", "-selection", "clipboard"],
-                input=text.encode(),
-                check=True,
-            )
-        return True
-    except (FileNotFoundError, subprocess.CalledProcessError):
-        return False
+    db_path = Path(cfg.learning.db_path) if cfg.learning.db_path else None
+    return KnowledgeStore(db_path=db_path)
 
 
 def prompt_action(cmd: str) -> str:
     try:
-        choice = console.input("  [dim]Run it?[/dim] [bold]\\[Y/n/c][/bold] ").strip().lower()
+        choice = console.input("  [dim]Run it?[/dim] [bold]\\[Y/n/c/e][/bold] ").strip().lower()
         if choice in ("", "y", "yes"):
             return "run"
         if choice in ("c", "copy"):
             return "copy"
+        if choice in ("e", "edit"):
+            return "edit"
         return "skip"
     except (KeyboardInterrupt, EOFError):
         return "skip"
@@ -136,14 +86,28 @@ def handle_command(query: str, cfg: VoxConfig, auto_execute: bool = False) -> No
         console.print("  [yellow]Query too long. Try a shorter description.[/yellow]\n")
         return
 
-    from vox.engine import translate
+    knowledge = _get_knowledge(cfg)
+    cwd = os.getcwd()
+    from_cache = False
 
-    try:
-        with console.status("[dim]Thinking...[/dim]", spinner="dots"):
-            cmd = translate(query, cfg)
-    except KeyboardInterrupt:
-        console.print("\n  [dim]Cancelled.[/dim]\n")
-        return
+    # Check learned patterns first (skip LLM if high-confidence match)
+    if knowledge and cfg.learning.auto_learn:
+        matches = knowledge.find_pattern(query, cwd=cwd)
+        if matches:
+            top = matches[0]
+            if top.confidence >= cfg.learning.min_confidence and top.success_count >= cfg.learning.min_success_count:
+                cmd = top.command
+                from_cache = True
+
+    if not from_cache:
+        from vox.engine import translate
+
+        try:
+            with console.status("[dim]Thinking...[/dim]", spinner="dots"):
+                cmd = translate(query, cfg, knowledge=knowledge, cwd=cwd)
+        except KeyboardInterrupt:
+            console.print("\n  [dim]Cancelled.[/dim]\n")
+            return
 
     if not cmd:
         console.print("  [red]Could not translate. Try rephrasing.[/red]\n")
@@ -154,12 +118,16 @@ def handle_command(query: str, cfg: VoxConfig, auto_execute: bool = False) -> No
         return
 
     dangerous = is_dangerous(cmd)
+    if from_cache:
+        console.print("\n  [dim cyan][learned][/dim cyan]")
     print_command(cmd, dangerous=dangerous)
 
     if auto_execute and not dangerous:
         rc = execute_command(cmd)
         if rc != 0:
             console.print(f"  [dim]exit {rc}[/dim]")
+        else:
+            _learn_success(knowledge, query, cmd, cwd)
         console.print()
         return
 
@@ -174,7 +142,27 @@ def handle_command(query: str, cfg: VoxConfig, auto_execute: bool = False) -> No
         rc = execute_command(cmd)
         if rc != 0:
             console.print(f"  [dim]exit {rc}[/dim]")
+            _learn_error(knowledge, cmd, cwd)
+        else:
+            _learn_success(knowledge, query, cmd, cwd)
         console.print()
+    elif action == "edit":
+        try:
+            corrected = console.input("  [dim]Correct command:[/dim] ").strip()
+        except (KeyboardInterrupt, EOFError):
+            corrected = ""
+        if corrected:
+            if knowledge:
+                knowledge.save_correction(query, cmd, corrected)
+                console.print("  [green]Saved correction.[/green]")
+            print_command(corrected, dangerous=is_dangerous(corrected))
+            action2 = prompt_action(corrected)
+            if action2 == "run":
+                console.print()
+                execute_command(corrected)
+                console.print()
+        else:
+            console.print()
     elif action == "copy":
         if copy_to_clipboard(cmd):
             console.print("  [green]Copied to clipboard.[/green]\n")
@@ -184,6 +172,21 @@ def handle_command(query: str, cfg: VoxConfig, auto_execute: bool = False) -> No
         console.print()
 
 
+def _learn_success(knowledge, query: str, cmd: str, cwd: str) -> None:
+    """Save a successful command to the knowledge store."""
+    if knowledge:
+        import sys
+
+        os_name = "macOS" if sys.platform == "darwin" else "Linux"
+        knowledge.save_pattern(query, cmd, cwd, os_name)
+
+
+def _learn_error(knowledge, cmd: str, cwd: str) -> None:
+    """Save a failed command to the knowledge store."""
+    if knowledge:
+        knowledge.save_error(cmd, "", cwd)
+
+
 # ── REPL ─────────────────────────────────────────────────────────────────────
 
 
@@ -200,7 +203,7 @@ def repl(cfg: VoxConfig) -> None:
         )
     )
     console.print("[dim]Type what you want to do. Ctrl+C to exit.[/dim]")
-    console.print("[dim]  !listen — voice input  |  !agent <task> — delegate to agent[/dim]")
+    console.print("[dim]  !listen — voice  |  !agent <task> — delegate  |  !learn — show patterns[/dim]")
 
     model = cfg.model.name
     status = check_ollama(cfg)
@@ -408,6 +411,47 @@ def cmd_config(args: argparse.Namespace, _cfg: VoxConfig) -> None:
         console.print("[dim]Usage: vox config {init|show|edit|path}[/dim]")
 
 
+def cmd_learn(args: argparse.Namespace, cfg: VoxConfig) -> None:
+    """Manage the self-learning knowledge store."""
+    knowledge = _get_knowledge(cfg)
+    if not knowledge:
+        console.print("[yellow]Learning is disabled. Enable in config: [learning] enabled = true[/yellow]")
+        return
+
+    action = args.learn_action or "show"
+
+    if action == "show":
+        patterns = knowledge.top_patterns(limit=20)
+        if not patterns:
+            console.print("[dim]No learned patterns yet. Use vox and it will learn over time.[/dim]")
+            return
+        console.print("[bold]Top learned patterns:[/bold]\n")
+        for p in patterns:
+            console.print(f"  [cyan]{p['query']}[/cyan] → [green]{p['command']}[/green] [dim]({p['uses']} uses)[/dim]")
+    elif action == "stats":
+        stats = knowledge.stats()
+        console.print("[bold]Knowledge store stats:[/bold]\n")
+        for key, val in stats.items():
+            console.print(f"  [cyan]{key}[/cyan]: {val}")
+    elif action == "clear":
+        knowledge.clear()
+        console.print("[green]Knowledge store cleared.[/green]")
+    elif action == "export":
+        data = knowledge.export_json()
+        if args.file:
+            Path(args.file).write_text(data)
+            console.print(f"[green]Exported to {args.file}[/green]")
+        else:
+            console.print(data)
+    elif action == "import":
+        if not args.file:
+            console.print("[yellow]Usage: vox learn import --file patterns.json[/yellow]")
+            return
+        data = Path(args.file).read_text()
+        count = knowledge.import_json(data)
+        console.print(f"[green]Imported {count} patterns.[/green]")
+
+
 # ── Main entry point ─────────────────────────────────────────────────────────
 
 
@@ -464,10 +508,21 @@ def _build_parser() -> argparse.ArgumentParser:
         help="Config action",
     )
 
+    # ── learn ─────────────────────────────────────────────────────────────
+    learn_parser = subparsers.add_parser("learn", help="Manage learned patterns")
+    learn_parser.add_argument(
+        "learn_action",
+        nargs="?",
+        choices=["show", "stats", "clear", "export", "import"],
+        default="show",
+        help="Learning action",
+    )
+    learn_parser.add_argument("--file", "-f", default=None, help="File path for export/import")
+
     return parser
 
 
-_SUBCOMMANDS = frozenset({"listen", "speak", "agent", "config"})
+_SUBCOMMANDS = frozenset({"listen", "speak", "agent", "config", "learn"})
 
 
 def main() -> None:
@@ -527,6 +582,8 @@ def main() -> None:
         cmd_agent(args, cfg)
     elif args.command == "config":
         cmd_config(args, cfg)
+    elif args.command == "learn":
+        cmd_learn(args, cfg)
     elif args.query:
         query = " ".join(args.query)
         handle_command(query, cfg, auto_execute=args.execute)
diff --git a/src/vox/config.py b/src/vox/config.py
index a7c18e4..a0e738f 100644
--- a/src/vox/config.py
+++ b/src/vox/config.py
@@ -48,12 +48,19 @@
 # theme = "monokai"
 # confirm_before_run = true
 # speak_responses = false
+
+[learning]
+# enabled = true
+# db_path = ""               # default: ~/.config/vox/knowledge.db
+# auto_learn = true           # save successful commands automatically
+# min_confidence = 0.9        # threshold to use cached patterns
+# min_success_count = 3       # minimum successes before trusting a pattern
 """
 
 
 @dataclass
 class ModelConfig:
-    name: str = "qwen2.5-coder:0.5b"
+    name: str = "nl2shell"
     provider: str = "ollama"
     api_url: str = "http://localhost:11434"
     temperature: float = 0.1
@@ -85,12 +92,22 @@ class UIConfig:
     speak_responses: bool = False
 
 
+@dataclass
+class LearningConfig:
+    enabled: bool = True
+    db_path: str = ""
+    auto_learn: bool = True
+    min_confidence: float = 0.9
+    min_success_count: int = 3
+
+
 @dataclass
 class VoxConfig:
     model: ModelConfig = field(default_factory=ModelConfig)
     voice: VoiceConfig = field(default_factory=VoiceConfig)
     agents: AgentsConfig = field(default_factory=AgentsConfig)
     ui: UIConfig = field(default_factory=UIConfig)
+    learning: LearningConfig = field(default_factory=LearningConfig)
 
 
 def _apply_env_overrides(cfg: VoxConfig) -> None:
@@ -109,6 +126,11 @@ def _apply_env_overrides(cfg: VoxConfig) -> None:
         "VOX_THEME": ("ui", "theme"),
         "VOX_CONFIRM": ("ui", "confirm_before_run"),
         "VOX_SPEAK": ("ui", "speak_responses"),
+        "VOX_LEARNING": ("learning", "enabled"),
+        "VOX_LEARNING_DB": ("learning", "db_path"),
+        "VOX_AUTO_LEARN": ("learning", "auto_learn"),
+        "VOX_MIN_CONFIDENCE": ("learning", "min_confidence"),
+        "VOX_MIN_SUCCESS_COUNT": ("learning", "min_success_count"),
     }
     for env_key, (section, attr) in env_map.items():
         val = os.environ.get(env_key)
@@ -156,6 +178,7 @@ def _apply_toml(cfg: VoxConfig, data: dict[str, Any]) -> None:
         "voice": cfg.voice,
         "agents": cfg.agents,
         "ui": cfg.ui,
+        "learning": cfg.learning,
     }
     for section_name, section_obj in section_map.items():
         section_data = data.get(section_name)
diff --git a/src/vox/engine.py b/src/vox/engine.py
index 828b306..2861f88 100644
--- a/src/vox/engine.py
+++ b/src/vox/engine.py
@@ -18,7 +18,7 @@
     "No explanations, no markdown, no code fences, no comments. Just the raw command."
 )
 
-DEFAULT_MODEL = "qwen2.5-coder:0.5b"
+DEFAULT_MODEL = "nl2shell"
 DEFAULT_API_URL = "http://localhost:11434"
 
 
@@ -80,16 +80,24 @@ class OllamaProvider(BaseProvider):
     def __init__(self, cfg: VoxConfig) -> None:
         self._cfg = cfg
 
-    def translate(self, query: str) -> str | None:
+    def translate(self, query: str, knowledge=None, cwd: str = "") -> str | None:
         """Translate natural language to a shell command via Ollama."""
         model = self._cfg.model.name
         api_url = self._cfg.model.api_url
         platform = get_platform()
 
+        # Build context-enriched system prompt
+        system_content = SYSTEM_PROMPT.format(platform=platform)
+        if knowledge and cwd:
+            context = knowledge.get_recent_context(cwd=cwd, limit=5)
+            if context:
+                hints = "\n".join(f"  {c['query']} → {c['command']}" for c in context)
+                system_content += f"\n\nRecent successful commands in this directory:\n{hints}"
+
         payload = {
             "model": model,
             "messages": [
-                {"role": "system", "content": SYSTEM_PROMPT.format(platform=platform)},
+                {"role": "system", "content": system_content},
                 {"role": "user", "content": query},
             ],
             "stream": False,
@@ -203,11 +211,11 @@ def _default_cfg() -> VoxConfig:
     return VoxConfig()
 
 
-def translate(query: str, cfg: VoxConfig | None = None) -> str | None:
+def translate(query: str, cfg: VoxConfig | None = None, knowledge=None, cwd: str = "") -> str | None:
     """Translate natural language to a shell command using the configured provider."""
     if cfg is None:
         cfg = _default_cfg()
-    return get_provider(cfg).translate(query)
+    return get_provider(cfg).translate(query, knowledge=knowledge, cwd=cwd)
 
 
 def query_llm(prompt: str, cfg: VoxConfig | None = None, system: str | None = None) -> str | None:
diff --git a/src/vox/executor.py b/src/vox/executor.py
new file mode 100644
index 0000000..600258e
--- /dev/null
+++ b/src/vox/executor.py
@@ -0,0 +1,47 @@
+"""Command execution and clipboard utilities."""
+
+from __future__ import annotations
+
+import shlex
+import subprocess
+import sys
+
+from rich.console import Console
+
+console = Console()
+
+
+def execute_command(cmd: str) -> int:
+    """Execute a shell command, returning the exit code."""
+    needs_shell = any(c in cmd for c in "|;&$`()<>")
+    try:
+        if needs_shell:
+            result = subprocess.run(cmd, shell=True, check=False)
+        else:
+            result = subprocess.run(shlex.split(cmd), check=False)
+        return result.returncode
+    except ValueError:
+        result = subprocess.run(cmd, shell=True, check=False)
+        return result.returncode
+    except FileNotFoundError:
+        console.print(f"  [red]Command not found: {cmd.split()[0]}[/red]")
+        return 127
+    except KeyboardInterrupt:
+        console.print("\n[dim][interrupted][/dim]")
+        return 130
+
+
+def copy_to_clipboard(text: str) -> bool:
+    """Copy text to the system clipboard. Returns True on success."""
+    try:
+        if sys.platform == "darwin":
+            subprocess.run(["pbcopy"], input=text.encode(), check=True)
+        else:
+            subprocess.run(
+                ["xclip", "-selection", "clipboard"],
+                input=text.encode(),
+                check=True,
+            )
+        return True
+    except (FileNotFoundError, subprocess.CalledProcessError):
+        return False
diff --git a/src/vox/knowledge.py b/src/vox/knowledge.py
new file mode 100644
index 0000000..a28e379
--- /dev/null
+++ b/src/vox/knowledge.py
@@ -0,0 +1,483 @@
+"""Self-learning knowledge store — SQLite-backed memory for command patterns, corrections, and errors."""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+DEFAULT_DB_PATH = Path.home() / ".config" / "vox" / "knowledge.db"
+MAX_PATTERNS = 10_000
+
+
+@dataclass
+class PatternMatch:
+    """A matched command pattern with confidence scoring."""
+
+    command: str
+    confidence: float
+    success_count: int
+    last_used: float
+    nl_query: str = ""
+    cwd: str = ""
+
+
+class KnowledgeStore:
+    """SQLite-backed self-learning store with 6 context layers.
+
+    Layer 1: Command patterns — validated NL→shell mappings that worked
+    Layer 2: User corrections — when the user rejects and provides the right command
+    Layer 3: Error patterns — commands that failed and what fixed them
+    Layer 5: Agent learnings — which agent works best for which task type
+    Layer 6: Session context — current directory, recent commands
+    """
+
+    def __init__(self, db_path: Path | None = None) -> None:
+        self._db_path = str(db_path or DEFAULT_DB_PATH)
+        self._db_path_obj = db_path or DEFAULT_DB_PATH
+        self._db_path_obj.parent.mkdir(parents=True, exist_ok=True)
+        self._has_fts5 = False
+        self._init_db()
+
+    def _get_conn(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(self._db_path, check_same_thread=False)
+        conn.row_factory = sqlite3.Row
+        conn.execute("PRAGMA journal_mode=WAL")
+        return conn
+
+    def _init_db(self) -> None:
+        conn = self._get_conn()
+        try:
+            # Layer 1: Command patterns
+            conn.execute("""
+                CREATE TABLE IF NOT EXISTS command_patterns (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    nl_query TEXT NOT NULL,
+                    shell_cmd TEXT NOT NULL,
+                    cwd TEXT DEFAULT '',
+                    os_name TEXT DEFAULT '',
+                    success_count INTEGER DEFAULT 1,
+                    last_used REAL NOT NULL,
+                    created_at REAL NOT NULL,
+                    UNIQUE(nl_query, shell_cmd)
+                )
+            """)
+
+            # Layer 2: User corrections
+            conn.execute("""
+                CREATE TABLE IF NOT EXISTS corrections (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    nl_query TEXT NOT NULL,
+                    rejected_cmd TEXT NOT NULL,
+                    correct_cmd TEXT NOT NULL,
+                    timestamp REAL NOT NULL
+                )
+            """)
+
+            # Layer 3: Error patterns
+            conn.execute("""
+                CREATE TABLE IF NOT EXISTS error_patterns (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    shell_cmd TEXT NOT NULL,
+                    error_output TEXT NOT NULL,
+                    fix_cmd TEXT DEFAULT '',
+                    cwd TEXT DEFAULT '',
+                    timestamp REAL NOT NULL
+                )
+            """)
+
+            # Layer 5: Agent learnings
+            conn.execute("""
+                CREATE TABLE IF NOT EXISTS agent_learnings (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    task_type TEXT NOT NULL,
+                    agent_name TEXT NOT NULL,
+                    success INTEGER NOT NULL DEFAULT 1,
+                    latency_ms INTEGER DEFAULT 0,
+                    timestamp REAL NOT NULL
+                )
+            """)
+
+            # Layer 6: Session context
+            conn.execute("""
+                CREATE TABLE IF NOT EXISTS sessions (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    session_id TEXT NOT NULL,
+                    cwd TEXT DEFAULT '',
+                    recent_cmds TEXT DEFAULT '[]',
+                    env_snapshot TEXT DEFAULT '{}',
+                    timestamp REAL NOT NULL
+                )
+            """)
+
+            # Try to create FTS5 index for fuzzy matching
+            try:
+                conn.execute("""
+                    CREATE VIRTUAL TABLE IF NOT EXISTS patterns_fts
+                    USING fts5(nl_query, content=command_patterns, content_rowid=id)
+                """)
+                self._has_fts5 = True
+            except sqlite3.OperationalError:
+                # FTS5 not available on this platform
+                self._has_fts5 = False
+
+            conn.commit()
+        finally:
+            conn.close()
+
+    # ── Layer 1: Command Patterns ────────────────────────────────────────────
+
+    def save_pattern(self, nl_query: str, shell_cmd: str, cwd: str = "", os_name: str = "") -> None:
+        """Save a successful NL→shell command mapping."""
+        now = time.time()
+        conn = self._get_conn()
+        try:
+            # Try to update existing pattern
+            cursor = conn.execute(
+                """UPDATE command_patterns
+                   SET success_count = success_count + 1, last_used = ?, cwd = ?, os_name = ?
+                   WHERE nl_query = ? AND shell_cmd = ?""",
+                (now, cwd, os_name, nl_query, shell_cmd),
+            )
+            if cursor.rowcount == 0:
+                # Insert new pattern
+                conn.execute(
+                    """INSERT INTO command_patterns (nl_query, shell_cmd, cwd, os_name, last_used, created_at)
+                       VALUES (?, ?, ?, ?, ?, ?)""",
+                    (nl_query, shell_cmd, cwd, os_name, now, now),
+                )
+                # Sync FTS index
+                if self._has_fts5:
+                    row = conn.execute(
+                        "SELECT id FROM command_patterns WHERE nl_query = ? AND shell_cmd = ?",
+                        (nl_query, shell_cmd),
+                    ).fetchone()
+                    if row:
+                        conn.execute(
+                            "INSERT INTO patterns_fts(rowid, nl_query) VALUES (?, ?)",
+                            (row["id"], nl_query),
+                        )
+                self._evict_if_needed(conn)
+            conn.commit()
+        finally:
+            conn.close()
+
+    def find_pattern(self, nl_query: str, cwd: str | None = None, limit: int = 3) -> list[PatternMatch]:
+        """Find matching patterns for a natural language query."""
+        conn = self._get_conn()
+        try:
+            matches: list[PatternMatch] = []
+
+            # First: check for correction overrides (Layer 2 takes priority)
+            correction = conn.execute(
+                "SELECT correct_cmd FROM corrections WHERE nl_query = ? ORDER BY timestamp DESC LIMIT 1",
+                (nl_query,),
+            ).fetchone()
+            if correction:
+                matches.append(
+                    PatternMatch(
+                        command=correction["correct_cmd"],
+                        confidence=1.0,
+                        success_count=999,
+                        last_used=time.time(),
+                        nl_query=nl_query,
+                    )
+                )
+                return matches
+
+            # Exact match (highest confidence)
+            exact = conn.execute(
+                """SELECT shell_cmd, success_count, last_used, cwd
+                   FROM command_patterns WHERE nl_query = ?
+                   ORDER BY success_count DESC, last_used DESC LIMIT ?""",
+                (nl_query, limit),
+            ).fetchall()
+            for row in exact:
+                matches.append(
+                    PatternMatch(
+                        command=row["shell_cmd"],
+                        confidence=1.0,
+                        success_count=row["success_count"],
+                        last_used=row["last_used"],
+                        nl_query=nl_query,
+                        cwd=row["cwd"],
+                    )
+                )
+
+            if matches:
+                return matches
+
+            # FTS5 fuzzy match (lower confidence, weighted by success_count)
+            if self._has_fts5:
+                fts_results = conn.execute(
+                    """SELECT cp.shell_cmd, cp.success_count, cp.last_used, cp.nl_query, cp.cwd,
+                              rank
+                       FROM patterns_fts fts
+                       JOIN command_patterns cp ON fts.rowid = cp.id
+                       WHERE patterns_fts MATCH ?
+                       ORDER BY rank
+                       LIMIT ?""",
+                    (nl_query, limit),
+                ).fetchall()
+                for row in fts_results:
+                    # Confidence based on FTS rank + success count
+                    base_confidence = min(0.85, 0.5 + (row["success_count"] * 0.05))
+                    matches.append(
+                        PatternMatch(
+                            command=row["shell_cmd"],
+                            confidence=base_confidence,
+                            success_count=row["success_count"],
+                            last_used=row["last_used"],
+                            nl_query=row["nl_query"],
+                            cwd=row["cwd"],
+                        )
+                    )
+            else:
+                # Fallback: LIKE-based fuzzy search
+                words = nl_query.lower().split()
+                if words:
+                    like_clause = " AND ".join("LOWER(nl_query) LIKE ?" for _ in words)
+                    like_params = [f"%{w}%" for w in words]
+                    like_results = conn.execute(
+                        f"""SELECT shell_cmd, success_count, last_used, nl_query, cwd
+                            FROM command_patterns WHERE {like_clause}
+                            ORDER BY success_count DESC, last_used DESC LIMIT ?""",  # noqa: S608
+                        [*like_params, limit],
+                    ).fetchall()
+                    for row in like_results:
+                        matches.append(
+                            PatternMatch(
+                                command=row["shell_cmd"],
+                                confidence=min(0.7, 0.3 + (row["success_count"] * 0.05)),
+                                success_count=row["success_count"],
+                                last_used=row["last_used"],
+                                nl_query=row["nl_query"],
+                                cwd=row["cwd"],
+                            )
+                        )
+
+            return matches
+        finally:
+            conn.close()
+
+    def _evict_if_needed(self, conn: sqlite3.Connection) -> None:
+        """Remove oldest/least-used patterns if over MAX_PATTERNS."""
+        count = conn.execute("SELECT COUNT(*) as c FROM command_patterns").fetchone()["c"]
+        if count > MAX_PATTERNS:
+            excess = count - MAX_PATTERNS
+            conn.execute(
+                """DELETE FROM command_patterns WHERE id IN (
+                       SELECT id FROM command_patterns
+                       ORDER BY success_count ASC, last_used ASC LIMIT ?
+                   )""",
+                (excess,),
+            )
+
+    # ── Layer 2: User Corrections ────────────────────────────────────────────
+
+    def save_correction(self, nl_query: str, rejected_cmd: str, correct_cmd: str) -> None:
+        """Save a user correction (rejected command → correct command)."""
+        conn = self._get_conn()
+        try:
+            conn.execute(
+                "INSERT INTO corrections (nl_query, rejected_cmd, correct_cmd, timestamp) VALUES (?, ?, ?, ?)",
+                (nl_query, rejected_cmd, correct_cmd, time.time()),
+            )
+            # Also save the correction as a pattern for future use
+            conn.commit()
+        finally:
+            conn.close()
+        # Save the corrected command as a pattern
+        self.save_pattern(nl_query, correct_cmd)
+
+    # ── Layer 3: Error Patterns ──────────────────────────────────────────────
+
+    def save_error(self, shell_cmd: str, error_output: str, cwd: str = "") -> None:
+        """Save a command that failed with its error output."""
+        conn = self._get_conn()
+        try:
+            conn.execute(
+                "INSERT INTO error_patterns (shell_cmd, error_output, cwd, timestamp) VALUES (?, ?, ?, ?)",
+                (shell_cmd, error_output[:2000], cwd, time.time()),
+            )
+            conn.commit()
+        finally:
+            conn.close()
+
+    def find_fix(self, shell_cmd: str, error_output: str) -> str | None:
+        """Find a known fix for a failed command."""
+        conn = self._get_conn()
+        try:
+            row = conn.execute(
+                """SELECT fix_cmd FROM error_patterns
+                   WHERE shell_cmd = ? AND fix_cmd != ''
+                   ORDER BY timestamp DESC LIMIT 1""",
+                (shell_cmd,),
+            ).fetchone()
+            return row["fix_cmd"] if row else None
+        finally:
+            conn.close()
+
+    # ── Layer 5: Agent Learnings ─────────────────────────────────────────────
+
+    def save_agent_result(
+        self, task_type: str, agent_name: str, success: bool, latency_ms: int = 0
+    ) -> None:
+        """Record which agent handled a task type and whether it succeeded."""
+        conn = self._get_conn()
+        try:
+            conn.execute(
+                "INSERT INTO agent_learnings (task_type, agent_name, success, latency_ms, timestamp) VALUES (?, ?, ?, ?, ?)",
+                (task_type, agent_name, int(success), latency_ms, time.time()),
+            )
+            conn.commit()
+        finally:
+            conn.close()
+
+    def best_agent_for(self, task_type: str) -> str | None:
+        """Find the historically best agent for a task type."""
+        conn = self._get_conn()
+        try:
+            # Look for agents with >70% success rate and at least 3 uses for similar tasks
+            words = task_type.lower().split()
+            if not words:
+                return None
+            like_clause = " OR ".join("LOWER(task_type) LIKE ?" for _ in words)
+            like_params = [f"%{w}%" for w in words]
+            row = conn.execute(
+                f"""SELECT agent_name,
+                           SUM(success) as wins,
+                           COUNT(*) as total,
+                           AVG(latency_ms) as avg_latency
+                    FROM agent_learnings
+                    WHERE {like_clause}
+                    GROUP BY agent_name
+                    HAVING total >= 3 AND (CAST(wins AS REAL) / total) > 0.7
+                    ORDER BY wins DESC, avg_latency ASC
+                    LIMIT 1""",  # noqa: S608
+                like_params,
+            ).fetchone()
+            return row["agent_name"] if row else None
+        finally:
+            conn.close()
+
+    # ── Layer 6: Session Context ─────────────────────────────────────────────
+
+    def save_session(self, session_id: str, cwd: str, recent_cmds: list[str]) -> None:
+        """Save session context."""
+        conn = self._get_conn()
+        try:
+            conn.execute(
+                "INSERT INTO sessions (session_id, cwd, recent_cmds, timestamp) VALUES (?, ?, ?, ?)",
+                (session_id, cwd, json.dumps(recent_cmds), time.time()),
+            )
+            conn.commit()
+        finally:
+            conn.close()
+
+    def get_recent_context(self, cwd: str | None = None, limit: int = 10) -> list[dict]:
+        """Get recent successful commands, optionally filtered by directory."""
+        conn = self._get_conn()
+        try:
+            if cwd:
+                rows = conn.execute(
+                    """SELECT nl_query, shell_cmd, cwd
+                       FROM command_patterns WHERE cwd = ?
+                       ORDER BY last_used DESC LIMIT ?""",
+                    (cwd, limit),
+                ).fetchall()
+            else:
+                rows = conn.execute(
+                    """SELECT nl_query, shell_cmd, cwd
+                       FROM command_patterns
+                       ORDER BY last_used DESC LIMIT ?""",
+                    (limit,),
+                ).fetchall()
+            return [{"query": r["nl_query"], "command": r["shell_cmd"], "cwd": r["cwd"]} for r in rows]
+        finally:
+            conn.close()
+
+    # ── Management ───────────────────────────────────────────────────────────
+
+    def stats(self) -> dict[str, int]:
+        """Return counts for each layer."""
+        conn = self._get_conn()
+        try:
+            return {
+                "patterns": conn.execute("SELECT COUNT(*) as c FROM command_patterns").fetchone()["c"],
+                "corrections": conn.execute("SELECT COUNT(*) as c FROM corrections").fetchone()["c"],
+                "errors": conn.execute("SELECT COUNT(*) as c FROM error_patterns").fetchone()["c"],
+                "agent_learnings": conn.execute("SELECT COUNT(*) as c FROM agent_learnings").fetchone()["c"],
+                "sessions": conn.execute("SELECT COUNT(*) as c FROM sessions").fetchone()["c"],
+            }
+        finally:
+            conn.close()
+
+    def top_patterns(self, limit: int = 20) -> list[dict]:
+        """Return the most-used command patterns."""
+        conn = self._get_conn()
+        try:
+            rows = conn.execute(
+                """SELECT nl_query, shell_cmd, success_count, last_used
+                   FROM command_patterns
+                   ORDER BY success_count DESC, last_used DESC LIMIT ?""",
+                (limit,),
+            ).fetchall()
+            return [
+                {
+                    "query": r["nl_query"],
+                    "command": r["shell_cmd"],
+                    "uses": r["success_count"],
+                    "last_used": r["last_used"],
+                }
+                for r in rows
+            ]
+        finally:
+            conn.close()
+
+    def export_json(self) -> str:
+        """Export all patterns as JSON for sharing/backup."""
+        conn = self._get_conn()
+        try:
+            rows = conn.execute(
+                "SELECT nl_query, shell_cmd, success_count, cwd, os_name FROM command_patterns"
+            ).fetchall()
+            data = [
+                {
+                    "query": r["nl_query"],
+                    "command": r["shell_cmd"],
+                    "uses": r["success_count"],
+                    "cwd": r["cwd"],
+                    "os": r["os_name"],
+                }
+                for r in rows
+            ]
+            return json.dumps(data, indent=2)
+        finally:
+            conn.close()
+
+    def import_json(self, json_str: str) -> int:
+        """Import patterns from JSON. Returns count of imported patterns."""
+        data = json.loads(json_str)
+        count = 0
+        for item in data:
+            query = item.get("query", "")
+            cmd = item.get("command", "")
+            if query and cmd:
+                self.save_pattern(query, cmd, item.get("cwd", ""), item.get("os", ""))
+                count += 1
+        return count
+
+    def clear(self) -> None:
+        """Reset the entire knowledge database."""
+        conn = self._get_conn()
+        try:
+            for table in ("command_patterns", "corrections", "error_patterns", "agent_learnings", "sessions"):
+                conn.execute(f"DELETE FROM {table}")  # noqa: S608
+            if self._has_fts5:
+                conn.execute("DELETE FROM patterns_fts")
+            conn.commit()
+        finally:
+            conn.close()
diff --git a/src/vox/safety.py b/src/vox/safety.py
new file mode 100644
index 0000000..d819919
--- /dev/null
+++ b/src/vox/safety.py
@@ -0,0 +1,44 @@
+"""Safety detection — dangerous command patterns and non-shell response filtering."""
+
+from __future__ import annotations
+
+import re
+
+DANGEROUS_PATTERNS = [
+    r"\brm\s+.*-\w*[rf]\w*",
+    r"\brm\s+-\w*R",
+    r"\bsudo\b",
+    r"\bdd\b\s+if=",
+    r"\bmkfs\b",
+    r"\bshred\b",
+    r"\bwipefs\b",
+    r"\b:\(\)\s*\{",
+    r"\bchmod\s+777\b",
+    r">\s*/dev/sd[a-z]",
+    r"\bsystemctl\s+(stop|disable|mask)\b",
+    r"\bkillall\b",
+    r"\breboot\b",
+    r"\bshutdown\b",
+    r"\bpoweroff\b",
+]
+
+NON_SHELL_PATTERNS = [
+    r"^\s*import\s+",
+    r"^\s*from\s+\w+\s+import\b",
+    r"^\s*def\s+\w+\(",
+    r"^\s*class\s+\w+",
+    r"^\s*<\?php",
+    r"^\s*<html",
+    r"^\s*\{\"",
+]
+
+
+def is_dangerous(cmd: str) -> bool:
+    """Check if a command matches any dangerous pattern."""
+    return any(re.search(p, cmd, re.IGNORECASE) for p in DANGEROUS_PATTERNS)
+
+
+def looks_like_shell(cmd: str) -> bool:
+    """Check if a response looks like a shell command (not Python, PHP, HTML, etc.)."""
+    first_line = cmd.split("\n")[0] if cmd else ""
+    return not any(re.search(p, first_line) for p in NON_SHELL_PATTERNS)
diff --git a/tests/test_cli.py b/tests/test_cli.py
index 60458b4..174ccbc 100644
--- a/tests/test_cli.py
+++ b/tests/test_cli.py
@@ -49,7 +49,7 @@ def test_version_flag(capsys):
             main()
         assert exc_info.value.code == 0
     captured = capsys.readouterr()
-    assert "0.3.0" in captured.out
+    assert "0.4.0" in captured.out
 
 
 @patch("vox.cli.cmd_listen")
@@ -401,14 +401,17 @@ def test_handle_command_too_long_query(mock_console, mock_translate):
     assert "too long" in printed.lower()
 
 
+@patch("vox.cli._get_knowledge", return_value=None)
 @patch("vox.cli.prompt_action", return_value="skip")
 @patch("vox.engine.translate", return_value="ls -la")
 @patch("vox.cli.console")
-def test_handle_command_translates_and_shows(mock_console, mock_translate, mock_prompt):
+def test_handle_command_translates_and_shows(mock_console, mock_translate, mock_prompt, mock_knowledge):
     """handle_command translates query and shows the command."""
     cfg = VoxConfig()
     handle_command("list files", cfg)
-    mock_translate.assert_called_once_with("list files", cfg)
+    mock_translate.assert_called_once()
+    args, _kwargs = mock_translate.call_args
+    assert args[0] == "list files"
 
 
 @patch("vox.engine.translate", return_value=None)
diff --git a/tests/test_config.py b/tests/test_config.py
index b0ce4bf..2b90507 100644
--- a/tests/test_config.py
+++ b/tests/test_config.py
@@ -14,7 +14,7 @@
 
 def test_default_config():
     cfg = VoxConfig()
-    assert cfg.model.name == "qwen2.5-coder:0.5b"
+    assert cfg.model.name == "nl2shell"
     assert cfg.model.provider == "ollama"
     assert cfg.model.api_url == "http://localhost:11434"
     assert cfg.model.temperature == 0.1
@@ -56,7 +56,7 @@ def test_apply_toml():
 
 def test_load_config_no_file():
     cfg = load_config(Path("/nonexistent/config.toml"))
-    assert cfg.model.name == "qwen2.5-coder:0.5b"
+    assert cfg.model.name == "nl2shell"
 
 
 def test_config_template_is_valid_toml():
diff --git a/tests/test_engine.py b/tests/test_engine.py
index 3115b49..2852184 100644
--- a/tests/test_engine.py
+++ b/tests/test_engine.py
@@ -43,4 +43,4 @@ def test_get_platform_returns_string():
 
 
 def test_default_model_is_small_coder():
-    assert "coder" in DEFAULT_MODEL or "nl2shell" in DEFAULT_MODEL
+    assert "nl2shell" in DEFAULT_MODEL or "nl2shell" in DEFAULT_MODEL
diff --git a/tests/test_knowledge.py b/tests/test_knowledge.py
new file mode 100644
index 0000000..dc689af
--- /dev/null
+++ b/tests/test_knowledge.py
@@ -0,0 +1,209 @@
+"""Tests for the self-learning knowledge store."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from vox.knowledge import KnowledgeStore, PatternMatch
+
+
+@pytest.fixture
+def store(tmp_path: Path) -> KnowledgeStore:
+    """Create a fresh knowledge store for each test."""
+    return KnowledgeStore(db_path=tmp_path / "test_knowledge.db")
+
+
+# ── Layer 1: Command Patterns ────────────────────────────────────────────────
+
+
+class TestCommandPatterns:
+    def test_save_and_find_exact_match(self, store: KnowledgeStore) -> None:
+        store.save_pattern("list files", "ls -la", "/home", "macOS")
+        matches = store.find_pattern("list files")
+        assert len(matches) == 1
+        assert matches[0].command == "ls -la"
+        assert matches[0].confidence == 1.0
+        assert matches[0].success_count == 1
+
+    def test_repeated_saves_increment_count(self, store: KnowledgeStore) -> None:
+        store.save_pattern("list files", "ls -la")
+        store.save_pattern("list files", "ls -la")
+        store.save_pattern("list files", "ls -la")
+        matches = store.find_pattern("list files")
+        assert matches[0].success_count == 3
+
+    def test_no_match_returns_empty(self, store: KnowledgeStore) -> None:
+        matches = store.find_pattern("something random")
+        assert matches == []
+
+    def test_multiple_commands_for_same_query(self, store: KnowledgeStore) -> None:
+        store.save_pattern("find large files", "find . -size +100M")
+        store.save_pattern("find large files", "du -sh * | sort -rh | head")
+        matches = store.find_pattern("find large files")
+        assert len(matches) == 2
+
+    def test_fuzzy_match_with_like(self, store: KnowledgeStore) -> None:
+        store.save_pattern("show disk usage", "df -h")
+        matches = store.find_pattern("disk usage")
+        assert isinstance(matches, list)
+
+    def test_limit_parameter(self, store: KnowledgeStore) -> None:
+        for i in range(10):
+            store.save_pattern(f"query {i}", f"cmd_{i}")
+        matches = store.find_pattern("query 5", limit=1)
+        assert len(matches) <= 1
+
+    def test_cwd_stored(self, store: KnowledgeStore) -> None:
+        store.save_pattern("git status", "git status", cwd="/my/project")
+        matches = store.find_pattern("git status")
+        assert matches[0].cwd == "/my/project"
+
+
+# ── Layer 2: Corrections ─────────────────────────────────────────────────────
+
+
+class TestCorrections:
+    def test_correction_overrides_pattern(self, store: KnowledgeStore) -> None:
+        store.save_pattern("list files", "ls")
+        store.save_correction("list files", "ls", "ls -la")
+        matches = store.find_pattern("list files")
+        assert matches[0].command == "ls -la"
+        assert matches[0].confidence == 1.0
+
+    def test_correction_saved_as_pattern(self, store: KnowledgeStore) -> None:
+        store.save_correction("show ports", "netstat", "lsof -i")
+        stats = store.stats()
+        assert stats["corrections"] == 1
+        assert stats["patterns"] >= 1
+
+
+# ── Layer 3: Error Patterns ──────────────────────────────────────────────────
+
+
+class TestErrorPatterns:
+    def test_save_error(self, store: KnowledgeStore) -> None:
+        store.save_error("docker ps", "Cannot connect to Docker daemon", "/home")
+        stats = store.stats()
+        assert stats["errors"] == 1
+
+    def test_find_fix_when_none(self, store: KnowledgeStore) -> None:
+        fix = store.find_fix("docker ps", "some error")
+        assert fix is None
+
+    def test_long_error_truncated(self, store: KnowledgeStore) -> None:
+        long_error = "x" * 5000
+        store.save_error("bad_cmd", long_error)
+        stats = store.stats()
+        assert stats["errors"] == 1
+
+
+# ── Layer 5: Agent Learnings ─────────────────────────────────────────────────
+
+
+class TestAgentLearnings:
+    def test_save_and_query_agent(self, store: KnowledgeStore) -> None:
+        for _ in range(5):
+            store.save_agent_result("fix code", "claude", success=True, latency_ms=1000)
+        best = store.best_agent_for("fix code")
+        assert best == "claude"
+
+    def test_no_data_returns_none(self, store: KnowledgeStore) -> None:
+        best = store.best_agent_for("unknown task")
+        assert best is None
+
+    def test_low_success_rate_not_returned(self, store: KnowledgeStore) -> None:
+        for _ in range(3):
+            store.save_agent_result("debug", "codex", success=False)
+        store.save_agent_result("debug", "codex", success=True)
+        best = store.best_agent_for("debug")
+        assert best is None
+
+    def test_minimum_uses_required(self, store: KnowledgeStore) -> None:
+        store.save_agent_result("test", "claude", success=True)
+        best = store.best_agent_for("test")
+        assert best is None
+
+
+# ── Layer 6: Session Context ─────────────────────────────────────────────────
+
+
+class TestSessionContext:
+    def test_save_and_get_context(self, store: KnowledgeStore) -> None:
+        store.save_pattern("list files", "ls", cwd="/project")
+        context = store.get_recent_context(cwd="/project")
+        assert len(context) == 1
+        assert context[0]["command"] == "ls"
+
+    def test_context_without_cwd(self, store: KnowledgeStore) -> None:
+        store.save_pattern("q1", "cmd1", cwd="/a")
+        store.save_pattern("q2", "cmd2", cwd="/b")
+        context = store.get_recent_context()
+        assert len(context) == 2
+
+    def test_save_session(self, store: KnowledgeStore) -> None:
+        store.save_session("sess-1", "/project", ["ls", "git status"])
+        stats = store.stats()
+        assert stats["sessions"] == 1
+
+
+# ── Management ───────────────────────────────────────────────────────────────
+
+
+class TestManagement:
+    def test_stats_all_zeros(self, store: KnowledgeStore) -> None:
+        stats = store.stats()
+        assert all(v == 0 for v in stats.values())
+
+    def test_clear_resets_everything(self, store: KnowledgeStore) -> None:
+        store.save_pattern("q", "cmd")
+        store.save_correction("q", "cmd", "cmd2")
+        store.save_error("cmd", "err")
+        store.save_agent_result("task", "claude", True)
+        store.save_session("s1", "/", ["ls"])
+        store.clear()
+        stats = store.stats()
+        assert all(v == 0 for v in stats.values())
+
+    def test_top_patterns_ordered(self, store: KnowledgeStore) -> None:
+        store.save_pattern("rare", "rare_cmd")
+        for _ in range(5):
+            store.save_pattern("common", "common_cmd")
+        top = store.top_patterns(limit=2)
+        assert top[0]["query"] == "common"
+        assert top[0]["uses"] == 5
+
+    def test_export_import_roundtrip(self, store: KnowledgeStore) -> None:
+        store.save_pattern("list files", "ls -la", "/home", "macOS")
+        store.save_pattern("show disk", "df -h", "/", "Linux")
+        exported = store.export_json()
+        data = json.loads(exported)
+        assert len(data) == 2
+        store.clear()
+        count = store.import_json(exported)
+        assert count == 2
+        matches = store.find_pattern("list files")
+        assert len(matches) == 1
+
+    def test_eviction(self, tmp_path: Path) -> None:
+        import vox.knowledge as k
+        old_max = k.MAX_PATTERNS
+        k.MAX_PATTERNS = 5
+        try:
+            store = KnowledgeStore(db_path=tmp_path / "evict.db")
+            for i in range(8):
+                store.save_pattern(f"query_{i}", f"cmd_{i}")
+            stats = store.stats()
+            assert stats["patterns"] <= 6
+        finally:
+            k.MAX_PATTERNS = old_max
+
+
+class TestPatternMatchDataclass:
+    def test_fields(self) -> None:
+        m = PatternMatch(command="ls", confidence=0.9, success_count=3, last_used=0.0)
+        assert m.command == "ls"
+        assert m.confidence == 0.9
+        assert m.nl_query == ""
diff --git a/tests/test_provider.py b/tests/test_provider.py
index 2ffa703..eeb0d74 100644
--- a/tests/test_provider.py
+++ b/tests/test_provider.py
@@ -21,7 +21,6 @@
     translate,
 )
 
-
 # ---------------------------------------------------------------------------
 # VAL-PROV-001: BaseProvider is abstract
 # ---------------------------------------------------------------------------
@@ -34,14 +33,13 @@ def test_base_provider_is_abstract():
     assert issubclass(BaseProvider, abc.ABC)
     try:
         BaseProvider()
-        assert False, "Should have raised TypeError"
+        raise AssertionError("Should have raised TypeError")
     except TypeError:
         pass
 
 
 def test_base_provider_has_abstract_methods():
     """BaseProvider declares abstract methods: translate, query, check."""
-    import abc
 
     # Collect abstract method names from the ABC
     abstracts = set()
@@ -246,7 +244,7 @@ def test_check_ready(mock_get):
     """check() returns 'ready' when model is found in /api/tags."""
     mock_resp = MagicMock()
     mock_resp.json.return_value = {
-        "models": [{"name": "qwen2.5-coder:0.5b"}]
+        "models": [{"name": "nl2shell"}]
     }
     mock_resp.raise_for_status = MagicMock()
     mock_get.return_value = mock_resp
@@ -300,7 +298,7 @@ def test_get_provider_unknown_raises():
     cfg.model.provider = "unknown_provider"
     try:
         get_provider(cfg)
-        assert False, "Should have raised ValueError"
+        raise AssertionError("Should have raised ValueError")
     except ValueError as e:
         assert "unknown_provider" in str(e)
 
@@ -335,7 +333,7 @@ def test_module_translate_delegates_to_provider(mock_post):
 def test_module_check_ollama_delegates(mock_get):
     """Module-level check_ollama() works as backward-compatible wrapper."""
     mock_resp = MagicMock()
-    mock_resp.json.return_value = {"models": [{"name": "qwen2.5-coder:0.5b"}]}
+    mock_resp.json.return_value = {"models": [{"name": "nl2shell"}]}
     mock_resp.raise_for_status = MagicMock()
     mock_get.return_value = mock_resp
 
@@ -362,7 +360,7 @@ def test_config_provider_setting_affects_factory():
     cfg2.model.provider = "future_provider"
     try:
         get_provider(cfg2)
-        assert False, "Should have raised ValueError for unknown provider"
+        raise AssertionError("Should have raised ValueError for unknown provider")
     except ValueError:
         pass
 
@@ -377,6 +375,6 @@ def test_utilities_unchanged():
     assert isinstance(SYSTEM_PROMPT, str)
     assert "{platform}" in SYSTEM_PROMPT
     assert isinstance(DEFAULT_MODEL, str)
-    assert "coder" in DEFAULT_MODEL
+    assert "nl2shell" in DEFAULT_MODEL
     assert isinstance(DEFAULT_API_URL, str)
     assert DEFAULT_API_URL.startswith("http")
diff --git a/tests/test_router.py b/tests/test_router.py
index e81238a..2a1aa28 100644
--- a/tests/test_router.py
+++ b/tests/test_router.py
@@ -2,19 +2,16 @@
 
 from __future__ import annotations
 
-from unittest.mock import MagicMock, patch
+from unittest.mock import patch
 
 from vox.agents.base import AgentResult
 from vox.agents.router import (
     ALL_AGENTS,
-    ROUTE_SYSTEM_PROMPT,
-    _pick_agent,
     discover_agents,
     route_and_run,
 )
 from vox.config import VoxConfig
 
-
 # ---------------------------------------------------------------------------
 # Helpers
 # ---------------------------------------------------------------------------
@@ -346,8 +343,9 @@ def test_force_agent_overrides_heuristic(self, mock_llm, mock_discover):
     def test_force_agent_via_env_var(self, mock_llm, mock_discover):
         """VOX_PREFERRED_AGENT env var acts as force_agent."""
         mock_discover.return_value = _available_coding_and_research()
-        with patch.object(ALL_AGENTS[2], "run", return_value=AgentResult(agent="gemini", output="done", exit_code=0)):
-            with patch.dict("os.environ", {"VOX_PREFERRED_AGENT": "gemini"}):
+        with patch.object(ALL_AGENTS[2], "run", return_value=AgentResult(agent="gemini", output="done", exit_code=0)), patch.dict("os.environ", {"VOX_PREFERRED_AGENT": "gemini"}):
+
+
                 result = route_and_run("fix bugs everywhere", _cfg())
         mock_llm.assert_not_called()
         assert "gemini" in result
diff --git a/uv.lock b/uv.lock
index 71c07d5..aac82a1 100644
--- a/uv.lock
+++ b/uv.lock
@@ -2438,6 +2438,31 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/14/25/b208c5683343959b670dc001595f2f3737e051da617f66c31f7c4fa93abc/rich-14.3.3-py3-none-any.whl", hash = "sha256:793431c1f8619afa7d3b52b2cdec859562b950ea0d4b6b505397612db8d5362d", size = 310458, upload-time = "2026-02-19T17:23:13.732Z" },
 ]
 
+[[package]]
+name = "ruff"
+version = "0.15.9"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/e6/97/e9f1ca355108ef7194e38c812ef40ba98c7208f47b13ad78d023caa583da/ruff-0.15.9.tar.gz", hash = "sha256:29cbb1255a9797903f6dde5ba0188c707907ff44a9006eb273b5a17bfa0739a2", size = 4617361, upload-time = "2026-04-02T18:17:20.829Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/0b/1f/9cdfd0ac4b9d1e5a6cf09bedabdf0b56306ab5e333c85c87281273e7b041/ruff-0.15.9-py3-none-linux_armv6l.whl", hash = "sha256:6efbe303983441c51975c243e26dff328aca11f94b70992f35b093c2e71801e1", size = 10511206, upload-time = "2026-04-02T18:16:41.574Z" },
+    { url = "https://files.pythonhosted.org/packages/3d/f6/32bfe3e9c136b35f02e489778d94384118bb80fd92c6d92e7ccd97db12ce/ruff-0.15.9-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:4965bac6ac9ea86772f4e23587746f0b7a395eccabb823eb8bfacc3fa06069f7", size = 10923307, upload-time = "2026-04-02T18:17:08.645Z" },
+    { url = "https://files.pythonhosted.org/packages/ca/25/de55f52ab5535d12e7aaba1de37a84be6179fb20bddcbe71ec091b4a3243/ruff-0.15.9-py3-none-macosx_11_0_arm64.whl", hash = "sha256:eaf05aad70ca5b5a0a4b0e080df3a6b699803916d88f006efd1f5b46302daab8", size = 10316722, upload-time = "2026-04-02T18:16:44.206Z" },
+    { url = "https://files.pythonhosted.org/packages/48/11/690d75f3fd6278fe55fff7c9eb429c92d207e14b25d1cae4064a32677029/ruff-0.15.9-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:9439a342adb8725f32f92732e2bafb6d5246bd7a5021101166b223d312e8fc59", size = 10623674, upload-time = "2026-04-02T18:16:50.951Z" },
+    { url = "https://files.pythonhosted.org/packages/bd/ec/176f6987be248fc5404199255522f57af1b4a5a1b57727e942479fec98ad/ruff-0.15.9-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:9c5e6faf9d97c8edc43877c3f406f47446fc48c40e1442d58cfcdaba2acea745", size = 10351516, upload-time = "2026-04-02T18:16:57.206Z" },
+    { url = "https://files.pythonhosted.org/packages/b2/fc/51cffbd2b3f240accc380171d51446a32aa2ea43a40d4a45ada67368fbd2/ruff-0.15.9-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:7b34a9766aeec27a222373d0b055722900fbc0582b24f39661aa96f3fe6ad901", size = 11150202, upload-time = "2026-04-02T18:17:06.452Z" },
+    { url = "https://files.pythonhosted.org/packages/d6/d4/25292a6dfc125f6b6528fe6af31f5e996e19bf73ca8e3ce6eb7fa5b95885/ruff-0.15.9-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:89dd695bc72ae76ff484ae54b7e8b0f6b50f49046e198355e44ea656e521fef9", size = 11988891, upload-time = "2026-04-02T18:17:18.575Z" },
+    { url = "https://files.pythonhosted.org/packages/13/e1/1eebcb885c10e19f969dcb93d8413dfee8172578709d7ee933640f5e7147/ruff-0.15.9-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:ce187224ef1de1bd225bc9a152ac7102a6171107f026e81f317e4257052916d5", size = 11480576, upload-time = "2026-04-02T18:16:52.986Z" },
+    { url = "https://files.pythonhosted.org/packages/ff/6b/a1548ac378a78332a4c3dcf4a134c2475a36d2a22ddfa272acd574140b50/ruff-0.15.9-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:2b0c7c341f68adb01c488c3b7d4b49aa8ea97409eae6462d860a79cf55f431b6", size = 11254525, upload-time = "2026-04-02T18:17:02.041Z" },
+    { url = "https://files.pythonhosted.org/packages/42/aa/4bb3af8e61acd9b1281db2ab77e8b2c3c5e5599bf2a29d4a942f1c62b8d6/ruff-0.15.9-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:55cc15eee27dc0eebdfcb0d185a6153420efbedc15eb1d38fe5e685657b0f840", size = 11204072, upload-time = "2026-04-02T18:17:13.581Z" },
+    { url = "https://files.pythonhosted.org/packages/69/48/d550dc2aa6e423ea0bcc1d0ff0699325ffe8a811e2dba156bd80750b86dc/ruff-0.15.9-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:a6537f6eed5cda688c81073d46ffdfb962a5f29ecb6f7e770b2dc920598997ed", size = 10594998, upload-time = "2026-04-02T18:16:46.369Z" },
+    { url = "https://files.pythonhosted.org/packages/63/47/321167e17f5344ed5ec6b0aa2cff64efef5f9e985af8f5622cfa6536043f/ruff-0.15.9-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:6d3fcbca7388b066139c523bda744c822258ebdcfbba7d24410c3f454cc9af71", size = 10359769, upload-time = "2026-04-02T18:17:10.994Z" },
+    { url = "https://files.pythonhosted.org/packages/67/5e/074f00b9785d1d2c6f8c22a21e023d0c2c1817838cfca4c8243200a1fa87/ruff-0.15.9-py3-none-musllinux_1_2_i686.whl", hash = "sha256:058d8e99e1bfe79d8a0def0b481c56059ee6716214f7e425d8e737e412d69677", size = 10850236, upload-time = "2026-04-02T18:16:48.749Z" },
+    { url = "https://files.pythonhosted.org/packages/76/37/804c4135a2a2caf042925d30d5f68181bdbd4461fd0d7739da28305df593/ruff-0.15.9-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:8e1ddb11dbd61d5983fa2d7d6370ef3eb210951e443cace19594c01c72abab4c", size = 11358343, upload-time = "2026-04-02T18:16:55.068Z" },
+    { url = "https://files.pythonhosted.org/packages/88/3d/1364fcde8656962782aa9ea93c92d98682b1ecec2f184e625a965ad3b4a6/ruff-0.15.9-py3-none-win32.whl", hash = "sha256:bde6ff36eaf72b700f32b7196088970bf8fdb2b917b7accd8c371bfc0fd573ec", size = 10583382, upload-time = "2026-04-02T18:17:04.261Z" },
+    { url = "https://files.pythonhosted.org/packages/4c/56/5c7084299bd2cacaa07ae63a91c6f4ba66edc08bf28f356b24f6b717c799/ruff-0.15.9-py3-none-win_amd64.whl", hash = "sha256:45a70921b80e1c10cf0b734ef09421f71b5aa11d27404edc89d7e8a69505e43d", size = 11744969, upload-time = "2026-04-02T18:16:59.611Z" },
+    { url = "https://files.pythonhosted.org/packages/03/36/76704c4f312257d6dbaae3c959add2a622f63fcca9d864659ce6d8d97d3d/ruff-0.15.9-py3-none-win_arm64.whl", hash = "sha256:0694e601c028fd97dc5c6ee244675bc241aeefced7ef80cd9c6935a871078f53", size = 11005870, upload-time = "2026-04-02T18:17:15.773Z" },
+]
+
 [[package]]
 name = "safetensors"
 version = "0.7.0"
@@ -3194,7 +3219,7 @@ wheels = [
 
 [[package]]
 name = "vox-shell"
-version = "0.3.0"
+version = "0.4.0"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },
@@ -3223,6 +3248,7 @@ voice = [
 [package.dev-dependencies]
 dev = [
     { name = "pytest" },
+    { name = "ruff" },
 ]
 
 [package.metadata]
@@ -3240,7 +3266,10 @@ requires-dist = [
 provides-extras = ["voice", "finetune", "all"]
 
 [package.metadata.requires-dev]
-dev = [{ name = "pytest", specifier = ">=8.4.2" }]
+dev = [
+    { name = "pytest", specifier = ">=8.4.2" },
+    { name = "ruff", specifier = ">=0.15.9" },
+]
 
 [[package]]
 name = "xxhash"