Personal real-world intelligence · v0.1
Your world, intelligently routed.
Q-Concierge learns what you like and keeps every trip as a persistent project — places, plans, facts, decisions. It makes real-world decisions on your machine: which detour is worth it, where to stack fuel with a gym and groceries, and when leaving beats sitting in the worst of the day. It works offline, stays local, and never calls a premium model unless it has to.
- 0
- premium calls without a key
- local
- SQLite on your disk
- 63
- deterministic tests
- 1
- dependency at runtime
$ concierge brief --city Boise
Daily Brief — Boise — 64° F, light rain late
[Morning] Best coffee + working cafes near you
[Route] 2 candidates along your corridor
[Alerts] 1 weather alive · 0 interruptions
leave by 10:40 to land inside the 15:00–20:00 sweet spot
01 · route intelligence
Detours worth taking, honestly priced.
Instead of optimizing just the route, Concierge scans your corridor and prices every detour in minutes, fuel, and time value — then filters by your preferences. A 12-minute pull-off for a place you already like beats a 40-minute one for a novelty you didn't ask for.
- Cross-track corridor scanning
- Added minutes + fuel + time value
- Personal-fit weighted reasons
$ concierge route --from Boise --to Minneapolis
Corridor Boise → Minneapolis (870 mi)
slc-costco-south 12m detour · fit 74% · score 0.61 · on-route
bozeman-rocks-gym 18m detour · fit 88% · score 0.58 · worth it
bismarck-fold-spa 26m detour · fit 81% · score 0.52 · borderline
mpls-lake-walk 0m · not on corridor · skipped
Best stops: Costco South → Rocks Alive Gym
02 · stop stacking
One stop. Four needs. No extra fuel.
Real stops rarely satisfy one need. Concierge clusters compatible needs — fuel, showers, gym, groceries, quiet work — along the route and ranks combined stops by added time and opportunity density. It turns several hurried pulls-offs into one planned anchor.
- Need-driven clustering (NeedKind)
- Clusters scored by opportunity density
- Works offline from your local knowledge graph
$ concierge stops --city Boise
EXIT 52 · fuel + gym + showers + groceries
+14m off-route · density 3.4 · stack score 0.82
one stop, four needs, zero extra fuel burn
03 · knows what you like
A model of taste, not a wall of tags.
Signal lands through feedback and visits: love, like, neutral, dislike, skip. The ranking engine blends personal fit, novelty, price sensitivity, and open-window fit — and explains its scores instead of just returning a list.
- Feedback/visit-driven preference weights
- Explainable scores per candidate
- Slice-based prompts — never your whole persona
$ concierge feedback --slug bbq --status dislike
$ concierge arrival --city Madison
[Eat] Cubic Roasters reason: loves local roasters (like)
[Move] Chain of Lakes reason: sunset window + water
[Avoid] consistent BBQ ranking dropped (disliked)
04 · best time to move
Leave when the road rewards you.
Departure is scored across candidate windows against daylight, traffic risk, and day-rating. Concierge doesn't just say 'traffic is bad' — it tells you the best window tonight and warns you off the worst one.
- Candidate-window scoring
- Daylight, traffic risk, and day-rating
- Clear worst-window warnings
$ concierge departure --from Boise --to Bozeman
Best: leave 14:00 → arrive 19:00 (score 82)
• lands inside the 15:00–20:00 sweet spot
• daylight until 20:25 · traffic risk falling
• 6:00 AM arrival scored 31 — worst window
live facts · research once
Research once. Reuse until stale.
Concierge never calls a model itself. It asks for exactly the facts it needs — a tiny, machine-readable ResearchRequest. An external agent (Grok, ChatGPT, your own web tools) returns ONE compact FactPacket. Concierge ingests, caches, and reasons deterministically. Same facts serve departure, route, fuel, tonight, brief — until they expire.
- ASK: pnpm concierge research-needed --for departure --area Denver --json
- INGEST: pnpm concierge facts ingest --file packet.json
- ORCHESTRATE: pnpm concierge orchestrate --intent departure --json → ready
- REUSE: pnpm concierge usage --json · freshFactsReused increments
- CONTROL: demo facts never pollute live plans (CONCIERGE_ALLOW_DEMO=false)
$ concierge research-needed --for departure --area Denver --route slc->denver --json
{ needed: [{type:WEATHER,required:true,fields:[...]}, {type:TRAFFIC,required:true,fields:[...]}] }
$ concierge facts ingest --file packet.json
Ingested 2 facts · skipped 0 · replaced 0
$ concierge orchestrate --intent departure --origin SLC --destination Denver --json
{ status:ready, result:{bestOption:{departureLabel:10:40}}, dataClass:live, factsUsed:2 }
$ concierge usage --json
{ externalResearchRounds:1, freshFactsReused:3, estTokensSaved:4800 }
17 fact types · TTLs
Every fact has a freshness horizon.
Only missing facts are requested. Fields are minimal — only what the engine reads. Requests batch by provider + location so an agent retrieves once, returns once.
Deterministic
Engines never auto-call a model
Fresher-credible
Conflicts resolve by freshness + confidence
Provenance
Every plan carries fact sources + dataClass
TTL-aware
Weather 3h · Traffic 1h · Fuel 4h · Closures 4h
WEATHER 180m road conditions for departure window
TRAFFIC 60m corridor congestion for leave-time
ROAD_CLOSURE 240m detours that shift timing
FUEL_PRICE 240m fresh station prices for economics
BUSINESS_HOURS 720m destination open window
EVENT 720m arrival-day events
SUNSET 1440m exact sunset for arrival
positioning · grok is the judgment layer
Grok is the judgment layer, not the search engine.
Concierge separates research from reasoning. The external agent searches, scrapes, and synthesizes the world into facts. Concierge applies your preferences, route geometry, and hard constraints to produce a plan you can trust. No hallucinated stops, no phantom fuel prices, no LLM tax on repeated questions.
- No auto-Grok: Concierge never calls a model by itself
- Minimal ResearchRequest: only required fields, deduplicated, batched
- FactPacket v1 schema: stable contract for agent integration
- dataClass tracking: live/demo/stored/derived — never mixed
- Usage accounting: freshFactsReused, externalResearchRounds, est. tokens saved
"Research once. Reuse until stale."
Provider-agnostic. Works with Grok, ChatGPT, or your own tools. Q-Concierge is an independent open-source project, not affiliated with xAI.
travel projects · persistent state
The project persists. The expensive agent doesn’t have to.
Q-Concierge is always there. A Travel Project holds the durable state — destinations, dates, plans, facts, decisions, costs. A Project Agent is only a temporary worker, spawned when the work genuinely justifies it, then discarded. It can be recreated any time from project state alone. Projects persist. Agents are optional.
- You see one assistant: Q-Concierge — plus a project label, not a bot per city
- A day trip to Boulder stays inside Project Denver; it does not fork a new project
- Dates, memories and facts survive every agent that comes and goes
- The project is named for you: Project Denver · Sep 24–30, 2026
inside a project
Everything about the trip, in one card.
No chat scrollback to dig through. The project holds the places, the facts and their freshness, the plans, and the decisions — with costs when you supply them.
- Continuity between days: yesterday’s choices shape today’s plan
- Freshness is visible — you know when a fact needs refreshing
- No duplicated state inside a model, nothing lost when an agent ends
- The expensive part only appears when the work earns it
Saved Places
considered · visited · rejected
Live Facts
fresh / stale, with provenance
Route Options
corridors, closures, detours
Plans
today · tonight · week
Decisions
and what is still unresolved
Costs
fuel, food, reservations
live sources · cheapest sufficient
Use intelligence where it matters, not where code will do.
Q-Concierge asks for the smallest set of facts it is actually missing, fetches them from the cheapest source that can supply them, and reuses them until they go stale. Weather, daylight and routes cost nothing. Paid sources and premium models are off by default — intelligence is added only where free data and code cannot do the job.
solar-noaa
FREEsunrise · sunset · twilight · golden hour
computed locally, no network
open-meteo
FREElive weather, no key
global, cached an hour
nominatim
LOWcity coordinates
a city is geocoded once, then cached
osrm
LOWlive route distance + duration
deterministic estimate as honest fallback
Road conditions, closures, traffic, fuel and events arrive as normalized facts from an agent, a tool, or you — Q-Concierge decides what to do with them.
optional project agent
Complex project? A temporary agent, only if justified.
Most travel questions are answered by cached facts and deterministic engines — no model at all. When a project is genuinely complex, a policy engine may authorize one temporary worker. It receives a small context pack, returns structured results, and is then discarded. The project never depends on it.
- Default is no agent — the policy engine has to justify one
- A worker gets a bounded context pack, not your database
- It returns structured results; the project stores the outcome
- It can be recreated any time from project state alone
- You never see a bot per city — only the project itself
single restaurant search → no agent
simple question → no agent
multi-city route, many constraints → maybe one
recurring monitoring → maybe one
spawns avoided are counted as efficiency, not failure
road-trip intelligence
Check what can change the decision — not everything on the road.
Official state road feeds tell you a road is closed. They don't tell you a road is fine. We use the first, and never infer the second. A shorter route with a published closure loses to a longer one with nothing reported, and when we can't read a feed at all we say so instead of guessing.
- Official state DOT feeds only — open data, no scraping
- An empty response means unknown, never clear
- A route we could not read is penalised, not assumed fine
- Preflight answers GO, DELAY, RECONSIDER ROUTE, or PARTIAL DATA
- Planning intelligence, never a safety guarantee
fuel, without guessing
Prices are the expensive part, so we ask about a handful. Open data gives us which stations exist — never what they charge. A price comes from an authorized API, a fact packet, or you.
20
STATIONS FOUND
5
PRICES CHECKED
1
STOP RECOMMENDED
the lowest posted price is not automatically the best stop — membership, detour fuel and added time are part of the decision
A closure with no published delay figure stays an advisory. We never invent minutes the source did not report.
discover many · verify few
Research the candidates that matter, not every place in town.
Open data tells you a gym with a sauna exists at a coordinate, for free. It does not tell you whether the steam room works today or what the day pass costs. So Q-Concierge discovers broadly, ranks everything locally at zero marginal cost, and spends verification effort on the handful of places that could actually change the answer.
- Discovery is free and open — OpenStreetMap, no key, no account
- Ranking runs on distance, detour, category, amenities and your preferences
- Only unresolved facts that could change the ranking become questions
- A missing tag means unknown, not no — OSM is incomplete, and we say so
- Missing opening hours never becomes “closed”
stop stack
Five places inside one detour beat five places in five detours. The score is for the cluster, not the individual venue.
1 detour · 5 needs covered · the slightly worse place wins
31
DISCOVER
open data · free · no key
36
RANK
local signals · 0 extra calls
5
VERIFY
only what changes the answer
3
RECOMMEND
differentiated, not exhaustive
just talk to it
You type sentences. It remembers the trip.
No commands to memorize, no project ids to copy, no providers to configure. Q-Concierge works out what you mean, keeps one project per trip, and fetches only the facts it is actually missing. It says what it needs rather than guessing.
- One project per trip — updates never create a duplicate
- Intent is read by deterministic parsing, not a model call
- If a fact is missing, it names the fact instead of inventing it
- A day trip like Tuesday in Boulder stays inside your Denver trip
- Feedback is stored as dimensions, never as a transcript
YOUI'm heading to Denver tomorrow.
Project Denver created.
Best departure data being checked.
Agent: not needed.
YOUI'll stay until October 2.
Project updated — no duplicate created.
YOUWhat should I do tonight?
Using your Denver project.
Agent: not needed.
companion · daily brief
A plan for today that actually uses today.
Every morning Concierge assembles a brief from local conditions, your preferences, and your own knowledge graph — not a generic feed. Tonight becomes a curated answer to 'what should I do tonight?', and the week plans the long arc.
brief()
today's blocks, alerts, timeline
tonight()
energy + budget aware picks
week()
7-day plan from your slices
$ concierge brief --city Boise
Daily Brief — 2026-09-23 — Boise
[Condition] Sunset 5:31 PM · best daylight from 10:00
[Plan] 07:30 coffee & planning
12:30 lunch — Tater Compass
17:00 recovery — River Den
[Traffic] avoid 16:45 departures on I-84
elastic cost · intelligence router
Premium models are the last resort.
Every task class is ranked against local-first executors first: database, deterministic engines, mock — then — only — optional web/API/LLM providers you enable with keys. Results are cached by freshness so the same question never re-costs. Usage accounting shows exactly how many premium calls were avoided.
- db + deterministic default on — zero keys required
- network executors disabled until a key exists in your environment
- freshness TTLs: 30 min → 90 days, cache-first answering
- usage ledger: calls, cache hits, tokens, avoided premium spend
lookup db → deterministic → mock
compute deterministic → db
retrieve db → web → mock
search web → chatgpt → mock
judgment chatgpt → grok → mock
synthesis grok → mock
result cache 1 hit · 0 premium calls
architecture · open source
Small by design.
One TypeScript library, an orchestrator over pure deterministic engines, an elastic provider router, and a local SQLite store powered by the built-in node:sqlite. Engines never touch the network because they don't need to.
why it matters
Open, local, and honest about it.
MIT license
Do whatever you want with it — keep the notice.
No telemetry
No analytics, no accounts, no phone-home.
Zero native deps
The only runtime dependency is commander.
Docs-first
Architecture, providers, privacy, and dev guides in-repo.
privacy · built in, not bolted on
Your trip plan never leaves your machine.
Local-first
Profile, preferences, visits, trips, and cache live in a local SQLite database in your home directory.
Offline by default
With no API keys set, every command is fully deterministic and local — zero network contact.
Opt-in network
Web/API/LLM executors stay disabled until you provide keys in your environment. Never in the repo.
No telemetry
No analytics, no error reporting, no shared IDs, no sign-up. Nothing phones home.
Reclaimable
concierge reset wipes memory; cache --clear empties provider cache. Delete the .db to start over.
Estimates only
Distances, fuel math, and departure windows are planning estimates — never safety-critical guidance.
faq
Straight answers.
Does it work without the internet?
Yes. With no API keys configured, every capability is deterministic and runs locally — ranking, corridors, fuel, stops, departure, briefs. Network executors are opt-in and disabled by default.
What is this 'intelligence router' really doing?
Each task class has a ranked list of executors (db → deterministic → mock → optional api/web/chatgpt/grok). The router picks the first enabled candidate, caches results by freshness, and records usage so you can see premium calls avoided.
Is the demo data real?
No. Places, fuel stations, events, trails, and example trips are fictional fixtures labeled 'Demo' so the whole product is explorable offline. Never rely on them as live data.
What about the 'Grok' name — is this from xAI?
No. Q-Concierge is an independent open-source project and is not affiliated with, endorsed by, or sponsored by xAI. You can use any compatible provider or none at all.
Which Node do I need?
Node.js 22.5 or newer, because the SQLite store uses the built-in node:sqlite module. That keeps native dependencies at zero.
Can I use it as a library?
Yes — it ships both a CLI and a typed library (new Concierge()). A local HTTP JSON API is available via concierge serve.
get started
Run your first brief in five minutes.
Clone, install, and get a personalized daily brief — fully offline. When you want the elastic layer, add a key and let the router spend it wisely.
MIT licensed · open source · local-first
git clone https://github.com/grokbot-concierge/grokbot-conciergecd grokbot-conciergepnpm install && pnpm build pnpm doctor # → healthy, offlinepnpm brief -- --city Boise # optional: go premium on your termsexport GROK_API_KEY=sk-...