🌌 Omnotica — Autonomous Curiosity Engine & Web Distiller

An autonomous background research daemon. Evaluates conversation logs in real-time, detects technical knowledge gaps, crawls the web for up-to-date documentation, and injects distilled insights back into context windows.

Quickstart • The Paradigm Shift • CLI Reference • Architecture • Subsystems • API Reference • Comparison Matrix • Roadmap

---

💡 The Paradigm Shift

Traditional agents use "reactive retrieval"—they only query vector databases or trigger search tools when explicitly told to do so. This causes friction and misses out-of-date documentation during complex architectural tasks.

Omnotica shifts memory retrieval to "proactive context synthesis":

1. Curiosity evaluation loop: A fast, local background model silently monitors inputs, checking for complex engineering terms, undocumented frameworks, or APIs.
2. Automated Search & Scrape: Fires high-precision search queries to fetch web documentation and distills long pages into structured chunks.
3. Double Injection Pipeline:
   • Short-Term Ephemeral: Synthesizes a 3-4 sentence factual brief and writes it to the active conversation context in the background.
   • Long-Term Permanent: Sends scraped data directly to OmniMem to permanently enhance the agent's knowledge base.

---

⚡ Quickstart

Prerequisites

• Python 3.11+
• uv (recommended for rapid dependency syncing)
• Ollama running locally (preferably with qwen2.5-coder or llama3.2 loaded)
• OmniMem running locally on port 8000 for long-term database storage (optional but recommended)

1. Clone & Setup

git clone https://github.com/axtontc/Omnotica.git
cd Omnotica

# Sync virtual environment using uv
uv sync

2. Verify with the Test Suite

Ensure prompt parsers, model selectors, and CLI dispatch works locally:

uv run python -m pytest tests/ -v

---

🛠️ CLI Reference

Start the Curiosity Daemon

Launch the background watcher to monitor the brain transcripts directory:

omnotica start

---

🏗 Architecture

flowchart TD
    A[Agent Workspace transcript.jsonl] -->|OS File System Event| B[Watchdog TranscriptWatcher]
    B -->|Thread Submit| Pool[ThreadPoolExecutor]
    Pool -->|Extract Clean Prompts| C[Curiosity Evaluator]
    C -->|Local Ollama Check| D{Needs Research?}
    D -->|Yes| E[DuckDuckGo Distiller]
    D -->|No| F[No-op Skip]
    E -->|Scraped Paragraph Chunks| G[Web Scraper]
    G -->|Store Permanently| H[OmniMem API /ingest]
    G -->|Summarize brief| I[LLM Factual Synth]
    I -->|JSON Injection Payload| J[Ephemeral Message Injector]
    J -->|File lock write| A

    style B fill:#1a1a2e,stroke:#3776AB,color:#fff
    style Pool fill:#16213e,stroke:#3776AB,color:#fff
    style C fill:#16213e,stroke:#3776AB,color:#fff
    style D fill:#1a1a2e,stroke:#ebc034,color:#000
    style J fill:#2ea043,stroke:#2ea043,color:#fff

Loading

---

🏗️ Core Subsystems

Subsystem	Folder / File	Responsibility
CLI Router	omnotica/cli.py	Handles incoming commands to route daemon startup configurations
Watcher Daemon	omnotica/core/watcher.py	Employs watchdog handlers to track filesystem changes, parse inputs, and submit tasks to pools
Curiosity Agent	omnotica/core/curiosity.py	Queries Ollama to determine knowledge gaps, formats search queries, and drives ingestion steps
Web Scraper & Distiller	omnotica/core/distiller.py	Hits DuckDuckGo search endpoints, scrapes text contents using BeautifulSoup, and extracts structural paragraph chunks
Context Injector	omnotica/core/injector.py	Communicates with local OmniMem nodes and formats ephemeral messages into system inbox paths

---

📖 API & Core Functions Reference

omnotica/core/curiosity.py

These functions evaluate knowledge gaps:

Function / Method	Parameters	Description
get_lightweight_model()	None	Queries local Ollama model lists to return the optimal available lightweight model for evaluation.
evaluate_knowledge_gap(context_text, convo_id, brain_dir)	str, str, Path	Generates system evaluation prompts and parses LLM recommendations.

omnotica/core/distiller.py

These functions manage crawling:

Function / Method	Parameters	Description
scrape_url(url)	str	Sends requests with mock User-Agents and filters out text bodies using BeautifulSoup.
run_search_and_scrape(query, max_chunks)	str, int	Runs queries against DuckDuckGo and aggregates scraped paragraphs.

omnotica/core/injector.py

These functions manage context updates:

Function / Method	Parameters	Description
inject_to_omnimem(chunks, concept, urls)	list[str], str, list[str]	Posts vector content blocks to local OmniMem endpoints.
inject_ephemeral_message(chunks, concept, urls, convo_id, brain_dir)	list[str], str, list[str], str, Path	Generates short-term briefs and dumps JSON message objects to system paths.

---

📊 Comparison Matrix

Feature	Standard Search MCP	Raw Web Scrapers	Omnotica
Real-time Conversation Watchers	❌	❌	✅ Yes (Watchdog)
Autonomous Gap Analysis	❌	❌	✅ Yes (Local LLM)
Automatic Context Injection	❌	❌	✅ Yes (Ephemeral Drops)
Dual Storage (OmniMem + Context)	❌	❌	✅ Yes (Permanent + Session)

---

🧰 Tech Stack

• Core Language: Python 3.11+
• System Monitor: watchdog (OS-level transcript change notifications)
• Web Crawling: BeautifulSoup4, duckduckgo-search
• Model Inference: Ollama API (qwen2.5-coder & llama3.2)
• Testing & Formatting: pytest, Ruff, mypy

---

🗺️ Roadmap

• Background filesystem watchers
• Local LLM curiosity evaluator
• DuckDuckGo search integration & BeautifulSoup crawler
• Ephemeral message injection and OmniMem ingestion pipelines
• Google Search API Support — Fallback to official Google search keys when rate-limited
• Interactive Question Prompts — Ask the user for permission before starting large scrapers
• Source Whitelists — Filter out low-quality documentation blogs automatically

---

🔗 Ecosystem Cross-Linking

Omnotica is the research arm of the Antigravity Swarm ecosystem:

Project	Description
AUI	Zero-latency cross-process UI automation for Windows and Web
MemMCP	Stdio-transport memory server using SQLite WAL and FAISS RRF
The-Skillbrary	FastMCP skill execution server and registry
Multiverse-Planner	Brute-forces optimal plans via timeline expansion and pruning
Fractal-Swarm-v2	Swarm agent orchestration state machines
OmniMem	PostgreSQL hybrid memory system for large enterprise swarms
AntiMem	Local memory compactor and context-gated daemon
The-Sentinel-Reviewer	Code quality gatekeeper running static audits and test runners

---

📜 License & Copyright

This project is licensed under the Apache License, Version 2.0. See the LICENSE file for details. Copyright (c) 2026 Axton Carroll.

---

⭐ If Omnotica helps keep your agentic knowledge bases fresh, consider giving it a star!



_{Built by Axton Carroll — "Nothing is impossible, we merely don't know how to do it yet."}