{"id":49768545,"url":"https://github.com/proffesor-for-testing/nagual-qe","last_synced_at":"2026-05-11T11:28:20.760Z","repository":{"id":352876052,"uuid":"1216980321","full_name":"proffesor-for-testing/nagual-qe","owner":"proffesor-for-testing","description":"Self-learning knowledge system for quality engineering. Rust, SQLite + optional PostgreSQL, ONNX embeddings, hybrid retrieval, Bayesian quality scoring.","archived":false,"fork":false,"pushed_at":"2026-05-06T09:27:40.000Z","size":2386,"stargazers_count":16,"open_issues_count":1,"forks_count":2,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-06T11:30:16.110Z","etag":null,"topics":["agentic-qe","ai-agents","knowledge-management","quality-engineering","reasoning-bank","rust","self-learning","testing"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/proffesor-for-testing.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-21T12:28:51.000Z","updated_at":"2026-05-06T09:27:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/proffesor-for-testing/nagual-qe","commit_stats":null,"previous_names":["proffesor-for-testing/nagual-qe"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/proffesor-for-testing/nagual-qe","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/proffesor-for-testing%2Fnagual-qe","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/proffesor-for-testing%2Fnagual-qe/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/proffesor-for-testing%2Fnagual-qe/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/proffesor-for-testing%2Fnagual-qe/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/proffesor-for-testing","download_url":"https://codeload.github.com/proffesor-for-testing/nagual-qe/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/proffesor-for-testing%2Fnagual-qe/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32892763,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-10T13:40:02.631Z","status":"online","status_checked_at":"2026-05-11T02:00:05.975Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-qe","ai-agents","knowledge-management","quality-engineering","reasoning-bank","rust","self-learning","testing"],"created_at":"2026-05-11T11:28:19.895Z","updated_at":"2026-05-11T11:28:20.747Z","avatar_url":"https://github.com/proffesor-for-testing.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Nagual-QE\n\n[![CI](https://github.com/proffesor-for-testing/nagual-qe/actions/workflows/rust.yml/badge.svg)](https://github.com/proffesor-for-testing/nagual-qe/actions/workflows/rust.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Rust 1.75+](https://img.shields.io/badge/rust-1.75%2B-orange)](https://www.rust-lang.org)\n\n**A Rust-native self-learning knowledge system for Quality Engineering.**\n\nNagual-QE stores every pattern, test insight, and decision you encounter,\nlearns which ones actually work, and surfaces the right one when you need it\nagain. It is a local-first, privacy-respecting memory layer for engineers and\ntheir AI agents.\n\n\u003e *\"The Tonal is the island of the known. The Nagual is the vast unknown\n\u003e surrounding the island. The warrior's path is not to destroy the Tonal, but\n\u003e to keep it lean so the Nagual can emerge.\"*\n\nNew here? Read **[learn-nagual.md](learn-nagual.md)** — a layered,\nearned-recognition onboarding walkthrough that takes you from your first\npattern to the Constitution in six steps. The full principles live in\n[NAGUAL_CONSTITUTION.md](NAGUAL_CONSTITUTION.md).\n\n---\n\n## What it does\n\n- **Stores** problem → solution patterns with provenance, tags, and embeddings\n- **Learns** from outcomes: every success or failure updates a Bayesian quality\n  score (Beta distribution), not just a scalar reward\n- **Retrieves** with hybrid search — full-text (FTS5) + cosine similarity over\n  128-dim embeddings + graph-boosted scoring\n- **Consolidates** near-duplicates automatically (BLAKE3 + cosine thresholds)\n- **Predicts** with Brier-calibrated confidence; self-scores its own accuracy\n- **Redacts PII** before any data ever leaves the local machine\n- **Serves** a browser dashboard + HTTP/WebSocket API + Unix socket for local\n  agent integration\n\nDesigned to be the memory layer behind AI-assisted QE workflows — but it works\nequally well as a standalone engineer's notebook.\n\n---\n\n## Why `nagual-qe`\n\nThis is the **public** edition of Nagual — the same core engine, shipped with\na QE-flavoured seed pattern set (optional) so you get value on day one. Use it\nto back an [agentic-qe](https://github.com/proffesor-for-testing/agentic-qe)\nfleet, or stand it up on its own.\n\n### Core features\n\n| Capability | Feature flag | Default |\n|---|---|---|\n| ReasoningBank (pattern storage + retrieval) | always on | ✅ |\n| Hash embedder (no external deps) | always on | ✅ |\n| ONNX embedder (all-MiniLM-L6-v2) | `onnx-embed` | ✅ |\n| KOS (lineage, witness, delta, tiers, epochs) | `kos` | ✅ |\n| HTTP + WebSocket dashboard | `serve` | opt-in |\n| Terminal UI | `tui` | opt-in |\n| MinCut graph clustering | `mincut` | opt-in |\n| Cross-domain transfer learning | `domain-expansion` | opt-in |\n| Meta-cognitive self-critique | `strange-loop-meta` | opt-in |\n\n---\n\n## What it looks like\n\n```console\n$ nagual knowledge store \"Flaky async test caused by race in setup fixture\" \\\n    --solution \"Add explicit await on the shared fixture. The fixture runs in a\n                tokio::spawn and the test starts before it completes ~5% of\n                the time. Using an Arc\u003cNotify\u003e fixes this.\" \\\n    --domain \"qe.flaky\" --tags \"async,race-condition,tokio\"\n  stored pattern 7a9f3b1c (domain=qe.flaky, reward=0.500, tier=booster)\n\n$ nagual knowledge search \"flaky async\"\n  1. qe.flaky  score=0.84  Flaky async test caused by race in setup fixture\n     Add explicit await on the shared fixture. The fixture runs in a\n     tokio::spawn and the test starts before it completes ~5% of the time.\n     Using an Arc\u003cNotify\u003e fixes this.\n\n$ nagual learn record 7a9f3b1c success --feedback \"Worked on CI too\"\n  recorded outcome — bayesian_score: Beta(2.0, 1.0) → mean 0.667 (1 trial)\n\n$ nagual status\n  Patterns:       515 (seed) + 3 (local)    Avg reward: 0.547\n  Embeddings:     518 / 518 (onnx)          DB size:    1.6 MB\n  Drift (7d):     +0.02                     Sessions:   1 active\n  Constitution:   enforce (audit)           Tier:       booster 3, reflex 0\n```\n\n**Reproduce it**: `bash scripts/demo.sh` (drops a temp DB so your real store\nstays untouched). Or record your own session:\n\n```bash\nbrew install asciinema\nasciinema rec demo.cast -c 'bash scripts/demo.sh'\n```\n\n---\n\n## Quick start\n\n### macOS\n\n```bash\n# Prereqs: Rust, ONNX Runtime\nbrew install onnxruntime\n\n# Build + install\ngit clone https://github.com/proffesor-for-testing/nagual-qe\ncd nagual-qe\nbash scripts/mac-setup.sh\n\n# Verify\nnagual status\nnagual knowledge store \"Flaky test caused by async race\" \\\n  --solution \"Add explicit await on the setup fixture\" \\\n  --domain \"qe.flaky\" --tags \"async,race-condition\"\nnagual knowledge search \"flaky async\"\n```\n\n### Linux (Debian/Ubuntu)\n\n```bash\n# Prereqs\nsudo apt-get install -y build-essential pkg-config libssl-dev sqlite3\n# ONNX Runtime (arm64 example — see docs/setup.md for x86_64)\nwget https://github.com/microsoft/onnxruntime/releases/download/v1.17.0/onnxruntime-linux-aarch64-1.17.0.tgz\ntar xf onnxruntime-linux-aarch64-1.17.0.tgz\nsudo cp onnxruntime-linux-aarch64-1.17.0/lib/libonnxruntime.so* /usr/lib/ \u0026\u0026 sudo ldconfig\n\n# Build\ncargo build --release\nsudo cp target/release/nagual /usr/local/bin/\n```\n\n### Without ONNX (hash embedder only)\n\n```bash\ncargo build --release --no-default-features --features kos\n```\n\n### Run the dashboard\n\n```bash\ncargo build --release --features serve\nnagual serve --port 3333\n# open http://localhost:3333\n```\n\n---\n\n## Documentation\n\n- [learn-nagual.md](learn-nagual.md) — **start here** — layered onboarding walkthrough\n- [docs/setup.md](docs/setup.md) — local installation (all platforms)\n- [docs/database-setup.md](docs/database-setup.md) — SQLite + optional PostgreSQL\n- [docs/gcloud-deploy.md](docs/gcloud-deploy.md) — production deployment on GCE\n- [docs/seeding-qe.md](docs/seeding-qe.md) — importing the optional QE seed\n- [docs/architecture.md](docs/architecture.md) — module map + data flow\n- [NAGUAL_CONSTITUTION.md](NAGUAL_CONSTITUTION.md) — the eight principles\n\n---\n\n## Data storage\n\n- **SQLite** at `./nagual.db` (or `~/.nagual/nagual.db`) — always.\n- **PostgreSQL** (optional) via `DualWriteAdapter` — needed for the\n  `ruvector-postgres` extension (HNSW + GNN + SONA) and multi-host deployments.\n\nNo data ever leaves your machine unless you explicitly enable cloud sync.\nWhen you do, the PII redactor strips 12 classes of sensitive strings\n(paths, IPs, emails, API keys, SSH keys, JWTs, phone numbers, etc.) before\nany write to PostgreSQL or any outbound HTTP call.\n\n---\n\n## Status\n\nPre-1.0, actively developed. The public surface is stable enough to build on,\nbut expect migration notes between minor versions. All changes are documented\nin [CHANGELOG.md](CHANGELOG.md).\n\n---\n\n## Contributing\n\nIssues and PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the local\ndevelopment loop, code style, and the test requirements we enforce before\nmerging.\n\n---\n\n## Acknowledgements\n\nNagual-QE stands on the work of three upstream projects:\n\n- **[RuVector](https://github.com/ruvnet/RuVector)** — the pgvector-compatible\n  PostgreSQL extension (GNN + SONA + hybrid search) that backs the optional\n  Postgres dual-write path. Nagual's `ruvector(128)` columns, cosine operator\n  class, and HNSW indexing all come from here.\n- **[Ruflo](https://github.com/ruvnet/ruflo)** — the agent workflow framework\n  whose memory primitives, hooks, and MCP tooling informed the shape of\n  Nagual's own hooks and swarm coordination.\n- **[agentic-qe](https://github.com/proffesor-for-testing/agentic-qe)** — the\n  sister QE fleet. Nagual-QE is designed to be the memory layer that an\n  agentic-qe swarm reads and writes through, and the two projects share a\n  common vocabulary for patterns, outcomes, and learning.\n\nThanks to the authors and contributors of all three.\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fproffesor-for-testing%2Fnagual-qe","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fproffesor-for-testing%2Fnagual-qe","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fproffesor-for-testing%2Fnagual-qe/lists"}