Hillock

A lightweight, 100% local memory engine built for edge hardware.

Traditional local RAG is heavy. Running dense vector databases and using 8B+ generative LLMs just to parse documents burns VRAM, chokes mid-range GPUs, and still hallucinates when asked about things it doesn't know.

Hillock was built to solve this. It replaces bloated vector databases and token-hungry extraction passes with a lightweight, three-tier architecture: a relational SQLite Knowledge Graph, Hebbian synaptic memory, and Hyperdimensional Computing (HDC).

It extracts facts, blocks unanswerable questions mathematically before they ever reach the LLM, and runs entirely in under 1.2 GB of VRAM.

Why use Hillock?

• Zero Hallucinations: A hard mathematical gate blocks questions it doesn't know the answer to. It refuses honestly instead of guessing.
• Extremely Fast Ingestion: It uses tensor-based classification instead of an LLM to read documents. It can ingest a 30-sentence document in about 5 seconds.
• Runs on a Potato: The entire pipeline fits in <1.2 GB VRAM and can even run CPU-only if needed.
• API Ready (New in v0.6.x): Hillock now includes an OpenAI-compatible API server. You can plug its hallucination-free memory directly into UIs like Open-WebUI or Obsidian.

---

🚀 Quick Start

Prerequisites: Python 3.10+ and Ollama running locally.

Option A: 1-Click Launch (Recommended)

The launcher scripts create the virtual environment, install dependencies, and start the console automatically.

Windows:

run.bat

Linux / macOS:

chmod +x run.sh
./run.sh

Option B: Manual Setup

git clone https://github.com/roandejager/Hillock.git
cd Hillock

python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows

# Install the engine and its dependencies
pip install -e .

# Download the required English language model
python -m spacy download en_core_web_sm

Optional: ONNX CPU Predicate Routing

Install the ONNX export tools and create the FP16 MiniLM model:

pip install -e ".[onnx-export]"
python export_to_onnx.py

This writes minilm.onnx with dynamic batch and sequence dimensions. The ONNX router uses the CPU execution provider and the same mean-pooled, normalized cosine ranking as the PyTorch predicate router:

from talon_engine import ONNXDynamicPredicateRouter

router = ONNXDynamicPredicateRouter(model_path="minilm.onnx")
predicates = router.select_top_predicates_batch(["Marie Curie was born in Warsaw."])

---

🕹️ How to Use Hillock

Because Hillock is decoupled, you can use it in three different ways depending on your needs.

1. The API Server (For Custom UIs)

You can run Hillock in the background and connect it to your favorite AI interface (like Open-WebUI or AnythingLLM).

python api.py

This starts a local server at http://localhost:8000. Just go into your UI's settings, set the OpenAI API Base URL to http://localhost:8000/v1, and chat normally.

2. The Terminal Console

If you prefer the classic hacker aesthetic, you can chat with your documents directly in the terminal.

python main.py

Helpful CLI Commands:

• /ingest [file.txt or .pdf] : Feed a document into the memory engine.
• /model [name] : Switch your local Ollama model on the fly.
• /mode [strict | balanced | conversational] : Change how the assistant talks.
• /inspect [entity] : Look under the hood at exactly what the engine knows about a topic.

3. The Python Library (For Developers)

You can import Hillock directly into your own Python applications.

from engine import IntegratedHillock

# Initialize the memory engine
my_brain = IntegratedHillock("my_database.db")

# Query it programmatically
answer, primed_nodes, hdc_traces, mode = my_brain.execute_chat_turn("What did Alan Turing crack?")
print(answer)

---

✅ Verification Suite

Hillock includes a standalone, GPU-free test suite that checks the core mathematical invariants, database locks, and gating logic. It is safe to wire into CI pipelines without a GPU runner.

python verify_hillock.py

---

🗺️ Roadmap to v1.0

The full, detailed roadmap is tracked in Issue #1: The Path to v1.0.

With our conversational agent and performance updates complete, our immediate next steps focus on automated data connectors for frictionless directory and vault ingestion.

---

💼 Commercial Licensing & Enterprise Options

Hillock is dual-licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) and a Commercial Closed-Source License.

If you are embedding Hillock inside a closed-source product, proprietary SaaS, or on-premise application without releasing your source code under AGPL-3.0, you must purchase a Commercial License.

What the Commercial License Includes

• AGPL-3.0 Exemption: Keep your product, custom integrations, and intellectual property completely closed-source and proprietary.
• Full Legal Indemnity: Commercial protection to distribute Hillock inside your proprietary apps, on-premise tools, or SaaS backends.
• Direct Integration Support: Priority email support directly with the maintainer for architecture design, performance tuning, and hardware pipelines.

License Tiers

• Startup License ($49/mo or $499/yr): Ideal for solo developers, indie hackers, and early-stage startups embedding Hillock into a single proprietary product.

  • 👉 Purchase Monthly License ($49/mo)
  • 👉 Purchase Annual License ($499/yr)

• Enterprise License & Custom Deployment ($2,500+/yr): For companies requiring custom SLAs, dedicated integration engineering, custom relation schemas, or invoice/PO payments.

  • ✉️️ Contact Maintainer for Enterprise Licensing

---

🤝 Sponsors & Community Support

Hillock is an independent, open-source research project built for engineers running local AI on consumer hardware. Supporting Hillock directly funds local edge-first AI research and puts your developer tool or infrastructure platform in front of engineers building with this repository.

One-Time Support:

• Tip or Buy a Coffee : Leave a custom one-time contribution to support ongoing open-source development.

Sponsorship Tiers:

• Backer ($15 per month): Your name or GitHub handle permanently listed in the README Backers section. Become a Backer.
• Featured Partner ($100 per month): Your product logo, link, and short description placed near the top of the README.
• Enterprise Sponsor ($300 per month): Large logo placement across both the README and documentation, plus social shoutouts.

Interested in becoming a Featured Partner or Enterprise Sponsor for your developer tool? Reach out directly via GitHub Discussions or browse our store:

• Visit the Lemon Squeezy Store

---

⚖️ Licensing & Contributions

Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

To keep the project open-source while preserving the option for future commercial dual-licensing, contributors must sign a standard Contributor License Agreement (CLA) via cla-assistant.io when opening a PR. See CONTRIBUTING.md and CLA.md.

📬 Contact & Collaboration

Hillock is an active research project by Roan de Jager.

If you are interested in custom memory integrations, consulting on edge-AI systems, or commercial licensing, feel free to reach out directly via email at contact.roandejager@gmail.com or open a discussion on GitHub.