SparkyWen/qcue: open-source knowledge, memory, and semantic-recall system

[!NOTE] BYOK — bring your own key. QCue runs entirely against your own model-provider key. It never ships, brokers, or sees your credentials, and the whole product runs keyless and offline in stub mode so you can explore it in seconds.

QCue is an open-source knowledge, memory, and semantic-recall system. Dump fleeting ideas — typed or spoken — into a fast daily feed; a bring-your-own-key LLM continuously distills that stream into a persistent, interlinked Markdown wiki ([[wikilinks]], an index.md, a log.md) that you can browse, query by recall, and open in any Markdown editor. A nightly Auto-Dream pass keeps the knowledge base coherent.

📑 Table of contents

• ✨ What is QCue
• 🔄 The daily loop
• 🧱 The three layers
• 🏗️ Architecture
• 🧰 Tech stack
• 📂 Repository layout
• 🚀 Quickstart
• 📚 Documentation
• 🗺️ Roadmap
• 🔐 A note on this repository’s history
• 🤝 Contributing
• 💬 Community
• 🛡️ Security
• 📄 License
• ™️ Trademark

✨ What is QCue

🔄 The daily loop

flowchart LR
    A["✍️ Capture<br/>(text / voice)"] --> B["🧩 Ingest<br/>distill into wiki pages"]
    B --> C["🔎 Recall<br/>agentic search over your wiki"]
    C --> D["🌙 Auto-Dream<br/>nightly consolidation"]
    D -. compounds .-> B

capture (text / voice)
   └─► conversation-ingest distills it into wiki pages (entities, concepts, sources)
          └─► recall: you ask, the model generates its own search patterns and answers
                 └─► nightly Auto-Dream consolidates & compounds the wiki

🧱 The three layers

QCue keeps a clean separation between what you wrote, what the LLM maintains, and the rules that govern structure:

🏗️ Architecture

QCue is three real code areas, layered into a strict acyclic stack.

• 🦀 The harness (qcue-rs/). The load-bearing seam between QCue and any LLM provider. A single turn loop drives a conversation and never branches on provider name — it reaches a provider only through a small dispatch trait (a scripted stub for tests, or live HTTP). Adding a provider is data, not new branches: a vendor is a declarative profile plus a few stateless hooks and wire-quirk entries. Everything normalizes into one internal message shape and one stream-event shape, so a session can fall back between providers without re-encoding. Credentials live in a pool with explicit health states; errors are classified once, then a retry loop maps the classification to exactly one of rotate / fall back / back off / abort.

• 💡 The idea engine (qcue-rs/). Dual representation: the Markdown body in a per-tenant vault is the source of truth; a database mirrors structure and frontmatter for fast queries and linting. A single write gate is the only place wiki bodies are written — it sanitizes links, updates the mirror, then writes the file. Recall is agentic. Auto-Dream runs as a background pass with cost checked before any provider call.

• 🌐 The backend (qcue-rs/). A multi-tenant Axum server: row-level security on every table (each request binds a tenant context), authentication, an encrypted BYOK vault, a job queue, server-sent-event and websocket channels for live turns and recall, and a CRDT sync hub. Background workers and the consolidation cron are feature-gated and disabled by default.

• 📱 The app (qcue_app/). Offline-first Flutter (Android + iOS). One data seam: a single API-client interface has a stub implementation (fixtures, keyless) and an HTTP implementation; an offline-aware decorator captures writes locally first and flushes idempotently, so screens are unaware of connectivity. Design tokens are centralized and enforced by an architecture test.

Crate layering law (enforced in CI): protocol → http → llm-api → providers → router → {wiki, ideas} → {backend, ffi}. protocol/ is serialization-only — anything crossing the Rust↔Dart boundary belongs there, and a codegen step exports a shared schema + Dart models with a drift test that fails CI if they go stale.

📎 More detail: docs/architecture.md · docs/design-decisions.md

🧰 Tech stack

📂 Repository layout

qcue/
├── qcue-rs/             # 🦀 Rust workspace — harness core + idea engine + multi-tenant backend
│   ├── protocol/        #    serde-only shared types (the Rust↔Dart boundary)
│   ├── http/ llm-api/   #    provider-neutral transport + typed wire + stream parsers
│   ├── providers/       #    declarative provider profiles + hooks + wire-quirk tables
│   ├── router/          #    THE HARNESS: turn loop, credential pool, retry/rotate/fallback, stub
│   ├── wiki/ ideas/     #    THE IDEA ENGINE: write-gate wiki, agentic recall, Auto-Dream
│   ├── app-server/      #    THE BACKEND: auth + BYOK vault + job queue + SSE/WSS + sync hub
│   └── migrations/      #    SQLx migrations (tenancy/RLS … sync)
│
├── qcue_app/            # 📱 Flutter app (Android + iOS)
│   └── lib/
│       ├── core/        #    API seam, offline cache, themes & design tokens, models
│       └── features/    #    the screens: capture · wiki · recall · activity · settings
│
├── design-system/      # 🎨 shared visual language & design tokens
└── docs/               # 📚 curated public documentation

🚀 Quickstart

[!TIP] The fastest way to explore QCue is stub mode — it runs the entire product with no API key and no network via seeded fixtures.

📱 App (Flutter)

cd qcue_app
flutter pub get
flutter test                                      # unit + widget + architecture tests
flutter analyze
flutter run --dart-define=QCUE_STUB=true          # offline/demo, seeded fixtures, keyless

🦀 Backend (Rust)

cd qcue-rs
cargo test --lib                                  # fast unit tests, no database required
cargo clippy --all-targets -- -D warnings
# Full integration suite (Postgres 16 + Redis 7) and running the server: see docs/architecture.md

Live-backend and provider-key setup are documented in docs/architecture.md.

📚 Documentation

🗺️ Roadmap

• Now — a clean, well-governed open-source project; an end-to-end stub mode for instant local exploration; better contributor onboarding.
• Next — a generic, self-host-oriented backend setup guide (local Postgres/Redis bootstrap, no private infrastructure); broader documented provider coverage; a stronger public CI story.
• Later — deeper recall and consolidation; a richer cross-platform app; community extensions.

Full detail: docs/roadmap.md. Open an issue to propose or discuss a direction.

🔐 A note on this repository’s history

This repository starts with a clean public history for security, third-party license hygiene, and internal-reference protection. The original private development history is preserved separately.

This is a deliberate engineering decision, not an attempt to hide the project’s maturity. Git history is a permanent exposure surface — it can carry old secrets, internal operations notes, deployment topology, third-party material that cannot be relicensed, and large artifacts. Rather than rewrite a long private history and hope nothing was missed, QCue publishes a curated, audited snapshot and develops openly from here. See DEVELOPMENT_HISTORY.md for the full rationale and what is / isn’t included.

🤝 Contributing

Contributions are welcome! 🎉 Start with CONTRIBUTING.md and the CODE_OF_CONDUCT.md. For anything large, open an issue to discuss before implementing. A good first step is running the app in stub mode (above) to see the whole product end to end.

💬 Community

Have feedback, questions, or want to build QCue together? Join our user group on WeChat — we'd love to hear how you use QCue, and developers are warmly welcome to help shape where it goes next. The group is primarily Chinese-speaking, but everyone is welcome.

Scan to join the QCue · 第二大脑 WeChat group.

[!NOTE] WeChat group QR codes rotate roughly every 7 days. If the code above has expired, please open an issue or email [email protected] and we'll add you.

🛡️ Security

Please report vulnerabilities privately — do not open public issues for security matters. See SECURITY.md.

[!WARNING] BYOK reminder: never commit provider API keys, tokens, credentials, private keys, or production configuration. QCue is designed so secrets never reach logs or the database — keep it that way.

📄 License

QCue is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) — see LICENSE. Because QCue can be operated as a network service, AGPL-3.0 ensures that modifications offered to users over a network are also made available as source. See also NOTICE and THIRD_PARTY_NOTICES.md.

™️ Trademark

The QCue name, logo, and brand assets are reserved. The AGPL-3.0 grant covers source code, not brand usage. See TRADEMARKS.md.