Local-AI Agent v0.8.9.19-beta

Gemini-3.1-flash-lite   Openrouter/free   Local-Ai Model

---

How the Agent Works

All configurations and custom shortcuts are managed in ai-context.md.

• Direct (No Session): Sub-millisecond Jaccard matching (jaccard_search) instantly routes custom keywords to your local terminal.
• Single-Turn Agent (ai <query>): Returns a single response directly to your shell prompt without loading an active conversation.
• Multi-Turn Chat (ai alone): Starts a persistent terminal session with multi-turn context tracking.
• Workspace Agents (ai init <path>): Indexes your directory into a lightweight codebase graph and boots up a codebase-aware chat.

---

CLI Launch Interface

╭──────────────────────────────────────────────╮
│  >_ Local-AI Agent                           │
│                                              │
│  model:     local-model                      │
│  directory: ...-ai/projects/session-test     │
│  skill:     init                             │
│  database:  active (3 facts, 109 turns)      │
╰──────────────────────────────────────────────╯
[sys] Startup context: 104 tokens | Ctrl+C to exit.

Agent: Workspace loaded. Awaiting instructions.
❯ 

---

Temporal Personality Memory (TPM)

Evolving with your workspace, learning your habits, and standardizing your identity.

• Weaviate Engram's active reconciliation concepts with Noema's local Markdown file system.

---

Codebase Graph Mapper & Relational Index

Building flat shorthand maps and queryable call graphs.

• Graphify's codebase mapping with codebase-memory-mcp's relationship queries.

---

System Administration & Diagnostics

Inspecting package updates, monitoring system health, and optimizing performance...

• log-checker and system-health live diagnostics with aur-audit, security-audit, update-inspector zero-trust auditing, system-optimizer resource adjustments, ai-status routing, and ai-commit hooks.

---

Core Capabilities

Core	Capability	Description
Performance	Zero-Daemon	0% idle CPU/RAM. Ultra-light execution.
Intelligence	Scalability	Optimized from Qwen3.5 2B up to frontier models.
Resiliency	Fallbacks	Automatically cascades: Gemini → OpenRouter → Local.
Safety	Zero-Trust Guardrails	Intercepts destructive commands before shell execution.
Integration	Dynamic Context	On-demand compilation of system specs and file contents.
Optimization	Token-Slasher	Custom tool and skill integration built for minimal token use.
Interface	Conversational TUI	Rich, multi-turn chat sessions directly in the terminal.
Auditability	Zero-Dependency	Under 350 lines of modular, standard-library Python.

---

TUI Carousel & Input Controls

• Up / Down Arrow Keys: Cycle through available ranked selections.
• Enter: Execute the highlighted command (or initialize a workspace if the selection is a directory path).
• Esc / Right Arrow / Ctrl+C: Cancel/Skip the active menu, memory-recall, or tool authorization prompt cleanly.

~ ❯ weather
[01/02] ❯ [weather full] curl -s wttr.in | cat
:: ↵ run  Esc:

---

Command Reference

1. Global Shell Commands

Executed directly from your terminal prompt.

Command	Description
ai	Launch an interactive, multi-turn chat session.
ai <query>	Get an instant, one-shot answer, straight back to your shell prompt.
ai init <path>	Launch (or create) a codebase-aware workspace agent.
hs / hist	Interactively search or view active workspace history.md.

2. Active Session Commands

Typed directly inside an active chat session.

Command	Description
/skill <query> (or /s)	Search and load dynamic specialist skills on-the-fly.
view file <path> (or read)	Dynamically read local files directly into your model context.
-save <tag> / -load	Save active states or rollback/clone snapshots (with Global Handoff).
/f / /t / /b / /a	Trigger prompt-generating subroutines: Follow-up, Thinking, Brainstorm, or All.

3. Modular Toggle & Diagnostic Switches

Typed inside an active chat session to adjust settings.

Command	Description
/clear / /reset	Reset Session context, local chat history, and the SQLite TPM table.
/d / /e	Disable / Enable the context-aware grammar & spellchecker.
/m	Toggle long-term memory and TPM reconciliation ON/OFF.
/stats / /tok	Diagnostics: Toggle real-time speed metrics or view live token usage.

---

Agent Blueprint

Add your shortcuts, commands, and workspaces to ai-context.md.

# --- Weather & Live Networking ---
[TOOL] curl -s wttr.in --cat ---> weather full, wttr, weather
[TOOL] curl -s "wttr.in/?format=3" --cat ---> weather simple, wttr, weather

# --- Local-Ai Agent Blueprint (CheatSheet) ---
~/.config/local-ai/tools/blueprint --leaf ---> cheatsheet, blueprint, bp, cs

---

Setup & Prerequisites

# 1. Optional: Install terminal rendering utilities
# (mdcat enables beautiful terminal markdown formatting)
yay -S mdcat

# 2. Install the required requests dependency
# Arch: sudo pacman -S python-requests
# Debian/Ubuntu: sudo apt install python3-requests
# macOS / Other: pip install requests
sudo pacman -S python-requests

# 3. Clone the repository locally
git clone https://github.com/j5onrf/local-ai.git ~/.config/local-ai

# 4. Add the environment hook into Bash & reload your profile
echo '[ -f "$HOME/.config/local-ai/ai-hook.sh" ] && source "$HOME/.config/local-ai/ai-hook.sh"' >> ~/.bashrc
source ~/.bashrc

# 5. Create your private configuration file (No global exports needed!)
# Fill in only what you use; the rest defaults safely.
# The agent reads this dynamically on every run with zero terminal restarts.
nano ~/.config/local-ai/.env

Configuration Example (.env):

# Google Gemini API Configurations
GEMINI_API_KEY="AIzaSyYourFullGeminiApiKeyHere"
CLOUD_MODEL="gemini-3.1-flash-lite"

# OpenRouter API Configurations
OPENROUTER_API_KEY="sk-or-v1-YourFullOpenRouterKeyHere"
OPENROUTER_MODEL="openrouter/free"

# Context Limits
AI_MAX_TOKENS=8192

---

Credits & License

• License: Licensed under the permissive MIT License.
• Contributions: Special thanks to suyadnya for the .env configuration architecture, macOS compatibility investigations, and high-velocity alias designs. Contributions are always welcome.