https://github.com/proffesor-for-testing/nagual-qe
Self-learning knowledge system for quality engineering. Rust, SQLite + optional PostgreSQL, ONNX embeddings, hybrid retrieval, Bayesian quality scoring.
https://github.com/proffesor-for-testing/nagual-qe
agentic-qe ai-agents knowledge-management quality-engineering reasoning-bank rust self-learning testing
Last synced: about 1 month ago
JSON representation
Self-learning knowledge system for quality engineering. Rust, SQLite + optional PostgreSQL, ONNX embeddings, hybrid retrieval, Bayesian quality scoring.
- Host: GitHub
- URL: https://github.com/proffesor-for-testing/nagual-qe
- Owner: proffesor-for-testing
- License: mit
- Created: 2026-04-21T12:28:51.000Z (2 months ago)
- Default Branch: master
- Last Pushed: 2026-05-06T09:27:40.000Z (about 2 months ago)
- Last Synced: 2026-05-06T11:30:16.110Z (about 2 months ago)
- Topics: agentic-qe, ai-agents, knowledge-management, quality-engineering, reasoning-bank, rust, self-learning, testing
- Language: Rust
- Size: 2.28 MB
- Stars: 16
- Watchers: 0
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# Nagual-QE
[](https://github.com/proffesor-for-testing/nagual-qe/actions/workflows/rust.yml)
[](LICENSE)
[](https://www.rust-lang.org)
**A Rust-native self-learning knowledge system for Quality Engineering.**
Nagual-QE stores every pattern, test insight, and decision you encounter,
learns which ones actually work, and surfaces the right one when you need it
again. It is a local-first, privacy-respecting memory layer for engineers and
their AI agents.
> *"The Tonal is the island of the known. The Nagual is the vast unknown
> surrounding the island. The warrior's path is not to destroy the Tonal, but
> to keep it lean so the Nagual can emerge."*
New here? Read **[learn-nagual.md](learn-nagual.md)** — a layered,
earned-recognition onboarding walkthrough that takes you from your first
pattern to the Constitution in six steps. The full principles live in
[NAGUAL_CONSTITUTION.md](NAGUAL_CONSTITUTION.md).
---
## What it does
- **Stores** problem → solution patterns with provenance, tags, and embeddings
- **Learns** from outcomes: every success or failure updates a Bayesian quality
score (Beta distribution), not just a scalar reward
- **Retrieves** with hybrid search — full-text (FTS5) + cosine similarity over
128-dim embeddings + graph-boosted scoring
- **Consolidates** near-duplicates automatically (BLAKE3 + cosine thresholds)
- **Predicts** with Brier-calibrated confidence; self-scores its own accuracy
- **Redacts PII** before any data ever leaves the local machine
- **Serves** a browser dashboard + HTTP/WebSocket API + Unix socket for local
agent integration
Designed to be the memory layer behind AI-assisted QE workflows — but it works
equally well as a standalone engineer's notebook.
---
## Why `nagual-qe`
This is the **public** edition of Nagual — the same core engine, shipped with
a QE-flavoured seed pattern set (optional) so you get value on day one. Use it
to back an [agentic-qe](https://github.com/proffesor-for-testing/agentic-qe)
fleet, or stand it up on its own.
### Core features
| Capability | Feature flag | Default |
|---|---|---|
| ReasoningBank (pattern storage + retrieval) | always on | ✅ |
| Hash embedder (no external deps) | always on | ✅ |
| ONNX embedder (all-MiniLM-L6-v2) | `onnx-embed` | ✅ |
| KOS (lineage, witness, delta, tiers, epochs) | `kos` | ✅ |
| HTTP + WebSocket dashboard | `serve` | opt-in |
| Terminal UI | `tui` | opt-in |
| MinCut graph clustering | `mincut` | opt-in |
| Cross-domain transfer learning | `domain-expansion` | opt-in |
| Meta-cognitive self-critique | `strange-loop-meta` | opt-in |
---
## What it looks like
```console
$ nagual knowledge store "Flaky async test caused by race in setup fixture" \
--solution "Add explicit await on the shared fixture. The fixture runs in a
tokio::spawn and the test starts before it completes ~5% of
the time. Using an Arc fixes this." \
--domain "qe.flaky" --tags "async,race-condition,tokio"
stored pattern 7a9f3b1c (domain=qe.flaky, reward=0.500, tier=booster)
$ nagual knowledge search "flaky async"
1. qe.flaky score=0.84 Flaky async test caused by race in setup fixture
Add explicit await on the shared fixture. The fixture runs in a
tokio::spawn and the test starts before it completes ~5% of the time.
Using an Arc fixes this.
$ nagual learn record 7a9f3b1c success --feedback "Worked on CI too"
recorded outcome — bayesian_score: Beta(2.0, 1.0) → mean 0.667 (1 trial)
$ nagual status
Patterns: 515 (seed) + 3 (local) Avg reward: 0.547
Embeddings: 518 / 518 (onnx) DB size: 1.6 MB
Drift (7d): +0.02 Sessions: 1 active
Constitution: enforce (audit) Tier: booster 3, reflex 0
```
**Reproduce it**: `bash scripts/demo.sh` (drops a temp DB so your real store
stays untouched). Or record your own session:
```bash
brew install asciinema
asciinema rec demo.cast -c 'bash scripts/demo.sh'
```
---
## Quick start
### macOS
```bash
# Prereqs: Rust, ONNX Runtime
brew install onnxruntime
# Build + install
git clone https://github.com/proffesor-for-testing/nagual-qe
cd nagual-qe
bash scripts/mac-setup.sh
# Verify
nagual status
nagual knowledge store "Flaky test caused by async race" \
--solution "Add explicit await on the setup fixture" \
--domain "qe.flaky" --tags "async,race-condition"
nagual knowledge search "flaky async"
```
### Linux (Debian/Ubuntu)
```bash
# Prereqs
sudo apt-get install -y build-essential pkg-config libssl-dev sqlite3
# ONNX Runtime (arm64 example — see docs/setup.md for x86_64)
wget https://github.com/microsoft/onnxruntime/releases/download/v1.17.0/onnxruntime-linux-aarch64-1.17.0.tgz
tar xf onnxruntime-linux-aarch64-1.17.0.tgz
sudo cp onnxruntime-linux-aarch64-1.17.0/lib/libonnxruntime.so* /usr/lib/ && sudo ldconfig
# Build
cargo build --release
sudo cp target/release/nagual /usr/local/bin/
```
### Without ONNX (hash embedder only)
```bash
cargo build --release --no-default-features --features kos
```
### Run the dashboard
```bash
cargo build --release --features serve
nagual serve --port 3333
# open http://localhost:3333
```
---
## Documentation
- [learn-nagual.md](learn-nagual.md) — **start here** — layered onboarding walkthrough
- [docs/setup.md](docs/setup.md) — local installation (all platforms)
- [docs/database-setup.md](docs/database-setup.md) — SQLite + optional PostgreSQL
- [docs/gcloud-deploy.md](docs/gcloud-deploy.md) — production deployment on GCE
- [docs/seeding-qe.md](docs/seeding-qe.md) — importing the optional QE seed
- [docs/architecture.md](docs/architecture.md) — module map + data flow
- [NAGUAL_CONSTITUTION.md](NAGUAL_CONSTITUTION.md) — the eight principles
---
## Data storage
- **SQLite** at `./nagual.db` (or `~/.nagual/nagual.db`) — always.
- **PostgreSQL** (optional) via `DualWriteAdapter` — needed for the
`ruvector-postgres` extension (HNSW + GNN + SONA) and multi-host deployments.
No data ever leaves your machine unless you explicitly enable cloud sync.
When you do, the PII redactor strips 12 classes of sensitive strings
(paths, IPs, emails, API keys, SSH keys, JWTs, phone numbers, etc.) before
any write to PostgreSQL or any outbound HTTP call.
---
## Status
Pre-1.0, actively developed. The public surface is stable enough to build on,
but expect migration notes between minor versions. All changes are documented
in [CHANGELOG.md](CHANGELOG.md).
---
## Contributing
Issues and PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the local
development loop, code style, and the test requirements we enforce before
merging.
---
## Acknowledgements
Nagual-QE stands on the work of three upstream projects:
- **[RuVector](https://github.com/ruvnet/RuVector)** — the pgvector-compatible
PostgreSQL extension (GNN + SONA + hybrid search) that backs the optional
Postgres dual-write path. Nagual's `ruvector(128)` columns, cosine operator
class, and HNSW indexing all come from here.
- **[Ruflo](https://github.com/ruvnet/ruflo)** — the agent workflow framework
whose memory primitives, hooks, and MCP tooling informed the shape of
Nagual's own hooks and swarm coordination.
- **[agentic-qe](https://github.com/proffesor-for-testing/agentic-qe)** — the
sister QE fleet. Nagual-QE is designed to be the memory layer that an
agentic-qe swarm reads and writes through, and the two projects share a
common vocabulary for patterns, outcomes, and learning.
Thanks to the authors and contributors of all three.
---
## License
MIT — see [LICENSE](LICENSE).