Converloop

Converse. Correct. Remember. Repeat.

A local-first AI language tutor that turns every conversation into better practice next time.

English · 简体中文

Download · Website · Design · Issues

Note

Converloop is in preview. The core learning loop is ready for daily use. Packaged releases currently provide macOS builds; Windows is validated in CI and can be run from source.

Practice that remembers

• Local SQLite mastery records with evidence timelines; error, correct, introduced, and gap events are all traceable.
• Evidence records distinguish modality, assistance, elicitation, self-repair, and response latency; heavily assisted success stays auditable without counting as independent mastery.
• Markdown learner profile for explicit learning goals, practice preferences, active focus, known items, rarely attempted language moves, recent items, and expression gaps.
• AI preferences can affect conversation, correction, lessons, and reading help separately.
• Code selects due review items from weakness and an event-derived FSRS-lite stability/difficulty model, then weaves them into conversation and training.
• Adaptive practice plans choose cued recall, free recall, or cross-context transfer and fade or strengthen hints from the latest evidence.
• Known items are reused as scaffolds for explanation and transfer, so the system does not only focus on mistakes.
• Learning data view supports evidence inspection, manual edits, natural-language edit previews, and confirmed writeback.
• Learning data view suggests likely duplicate mastery keys using local text similarity; merges always require confirmation.
• Lesson review and drill writeback preview evidence before the learner confirms it into long-term memory.

Most AI tutors can answer the sentence in front of them. Converloop also remembers what that sentence revealed about your language learning—not your personal life—then uses the evidence to shape what comes next.

1. Converse	2. Correct	3. Remember	4. Revisit
Speak or type naturally. The reply streams first, so practice still feels like a conversation.	Corrections stay attached to your sentence, with a natural rewrite and an explanation in context.	Errors, correct usage, and expression gaps become traceable local learning signals.	Weak points return through later conversations, focused lessons, dictation, and drills.

• Built-in training modes: scenario practice, dictation, and weak-item quick drills.
• Dictation stores misheard words in a separate listening dimension and can adapt future sentences to revisit them.
• Weak-item quick drills turn due review items into short tasks that require active recall.
• Custom training modes use converloop/drill@1 Markdown documents: frontmatter defines mechanics, body sections define prompts.
• Drills can include topic recommendations, drill observers, session reports, import, and export.
• Focused lessons open teacher-style sessions around grammar, expression gaps, daily review, or a learner-defined goal.
• Task Agent can turn broad goals such as interview prep, business email, or a recurring expression need into a learning project and up to three lesson drafts.
• Projects include observable Can-do goals with a first-attempt task and a different-context transfer task.
• Text, Markdown, CSV, JSON, and PDF material can be imported locally to create grounded real-task projects. Images are previewed locally and use the learner's written description because the provider-neutral model interface is text-only.
• Practice stats card shows overview, trends, knowledge points, and recurring weak spots.

Made for real language use

Open to a useful next step

New chat is the shared start point across desktop, iPhone, and iPad. It keeps the greeting, current practice progress, recommended topics, and composer together. When a grammar error keeps recurring, one compact shortcut starts a focused teaching conversation directly from that learning record.

Conversation first, teaching alongside it

The conversation agent responds to what you meant while the tutor works in parallel. A mixed-language sentence becomes a useful “how do I say this?” moment instead of a broken red-and-green diff. Long chats keep rolling summaries, and /btw lets you ask an off-record side question without derailing the scene.

While you compose, one lightweight reply hint offers a useful next move without taking over the conversation. Reply ideas, beside it in the composer, opens a right-side detail view that expands the same suggestion into a main approach, alternative directions, target-language examples, and reusable sentence patterns or phrases. Corrections remain attached to the learner message, while evidence, review, and observations stay in Learning Data; there is no separate Coach entry in the top-right toolbar.

Evidence, not mysterious AI memory

Converloop keeps structured mastery records and the evidence behind them in local SQLite. Its readable Markdown profile is deliberately learning-only: goals, practice preferences, current focus, strengths, avoided language moves, recent items, and expression gaps. It does not retain identity, work, location, relationships, interests, routines, or life events. The model can observe and propose; deterministic code owns counts, state changes, review selection, and persistence. Marking an item as known records an explicit learner override without inventing a successful attempt or rewriting its evidence.

Keep the conversation focused on learning

Converloop uses one consistent AI conversation partner. Tone, difficulty, reply length, and practice style belong to your learning preferences or the current conversation—not to a fictional relationship that remembers your personal life.

Turn weak spots into the next activity

Review is woven back into use. Start a normal conversation, tap a recurring grammar point to diagnose it and practise it in chat, run scenario practice, or use Conversation Replay for listening and dictation built from your own material. Training reports and lesson reviews preview the evidence before it becomes part of long-term learning memory.

What you can do today

Talk and get corrected Streaming replies, a lightweight composer hint with expanded Reply ideas, inline corrections, natural rewrites, grammar notes, expression-gap teaching, and message-level conversation branching.	Build durable learning memory Evidence timelines, due review, known-item scaffolding, editable learner profiles, stats, and confirmed natural-language data edits.
Practice with voice Speech input, read-aloud, local and cloud speech providers, plus one Conversation Replay area for listening and dictation.	Train with a purpose One-tap grammar teaching conversations, scenario practice, weak-item quick drills, focused lessons, learning projects, custom Markdown drills, reports, and import/export packages.
Choose your own models OpenAI-compatible endpoints, Anthropic, Gemini, Claude and ChatGPT subscription sign-in paths, plus cloud or local speech options.	Shape the tutor Enable or extend built-in capabilities, then create observers, conversation actions, and reply transformers with auditable runs and guarded memory writes.

See the full implemented feature map

Conversation and correction

• Parallel streaming conversation and two-stage correction, so visible feedback does not wait for memory bookkeeping.
• Structured feedback with the corrected sentence, a more natural alternative, error span, native-language explanation, severity, and stable mastery key.
• One lightweight hint appears in the composer; its adjacent Reply ideas action opens related detail with a main approach, other directions, target-language examples, and reusable sentence patterns or phrases.
• Corrections stay on the learner message, and evidence, review, and observations remain in Learning Data instead of a general-purpose Coach panel.
• High-value learning actions stay visible; editing and extension actions move into a compact overflow menu.
• Multi-conversation sidebar with pinning, date groups, automatic titles, rolling summaries, context hints, /btw, and message-level branching/editing.

Conversation continuity

• One consistent AI conversation partner, with tone, difficulty, reply length, and practice behavior controlled by learner or conversation settings.
• Current-conversation history and rolling summaries stay scoped to that conversation.
• Cross-conversation continuity contains language-learning state only, never inferred personal facts or relationship history.

Learning memory and review

• Local mastery records for error, correct, introduced, expression-gap, and listening evidence.
• Code-selected due review and known-item scaffolding across conversation, lessons, dictation, and drills.
• Evidence-derived status stays intact when the learner manually marks an item as known; review uses the explicit override without fabricating counts.
• Evidence inspection, manual edits, natural-language edit previews, and confirmed lesson or drill writeback.

Training and focused lessons

• Scenario practice, adaptive dictation, due-item quick drills, and custom converloop/drill@1 Markdown training modes.
• Focused teacher-style sessions for grammar, expression gaps, daily review, or a learner-defined goal.
• Learning projects, lesson drafts, topic recommendations, drill observers, session reports, and package import/export.

Capabilities, reading, and speech

• Auditable built-in capabilities for correction, explanation, bilingual reading, selection analysis, conversation actions, and more.
• Custom observers, actions, and reply transformers with proposal-based access to long-term memory.
• Soniox streaming STT, OpenAI-compatible transcription, local Parakeet and Qwen3-ASR, Edge Read Aloud, and MiMo TTS.

Desktop and local data

• English and Chinese UI, onboarding, themes, accent colors, command palette, editable shortcuts, and update checks.
• Readable JSON backup and restore for conversations, learning-only data, profile, and non-secret settings; retired personal and relationship memories are never exported or restored.
• Operating-system secure credential storage; API keys and OAuth tokens are excluded from backups.

Local-first by design

• Your learning history stays inspectable. Conversations, mastery evidence, profiles, and non-secret settings are stored on your device and can be backed up as readable JSON.
• Secrets are separate. API keys and OAuth tokens use the operating system's secure credential vault and never enter backups.
• You choose the intelligence. Bring your own provider or compatible endpoint instead of being locked to a hosted model selected by the app.
• Network use is explicit. Content needed for a request is sent to the model, speech, or voice provider you configure; local providers can keep supported speech workflows on-device.

Install

macOS

Download the latest Apple Silicon or Intel DMG from GitHub Releases. On first launch, choose your languages and level, then configure a model provider in Settings.

Windows

Windows is a first-class target and its build is checked in CI. Packaged Windows releases are not published yet; use the source setup below for now.

Build from source

Prerequisites

• Node.js 24
• pnpm 11 through Corepack

git clone https://github.com/jovidalao/Converloop.git
cd Converloop
corepack enable
pnpm install
pnpm dev

pnpm dev starts the Vite renderer and the Electron main/preload processes together, with hot reload for renderer changes and automatic restarts for native code changes. Keep this command running while developing and press Ctrl+C to stop it. Install dependencies on the operating system where you will run the app; native speech and credential packages are platform-specific and node_modules should not be copied between macOS and Windows.

Configure a provider

1. Start Converloop with pnpm dev.
2. Open Settings and select a model provider and model.
3. Enter the credential or complete the available OAuth sign-in flow in the app.

Credentials are stored in the operating system's secure credential vault. Do not put provider keys in .env, VITE_*, shell history, or source files: Vite embeds VITE_* values into renderer assets. The checked-in .env.example intentionally contains guidance only and no credentials.

Development commands

Command	Purpose
pnpm dev	Start the desktop app with Vite HMR
pnpm build	Type-check and build the renderer and Electron bundles
pnpm test	Run Vitest
pnpm check	Run Biome and TypeScript checks
pnpm format	Apply formatting fixes
pnpm dist	Build desktop packages with electron-builder
pnpm verify:package	Verify that a packaged app contains its native modules

Package locally

pnpm dist

Artifacts are written to release/. The command packages the current platform, then checks the Electron archive and native credential/speech modules before it finishes. Local macOS packages are unsigned unless signing credentials are provided; official release builds sign and notarize in CI.

Back up or move learning data

Use the in-app Export and Import actions to move learning data between installs. Backups contain conversations, learning evidence, the learning profile, and explicitly supported non-secret settings; API keys and OAuth tokens never enter the backup. The portable exchange shape is documented in docs/converloop-portable-backup-v1.schema.json.

Repository map

Path	Purpose
src/	React renderer, learning agents, database queries, and UI
electron/	Electron main process, preload bridge, IPC handlers, and native modules
scripts/	Development runner, Electron bundling, and package verification
docs/design.md	Public product boundaries and long-term architecture principles
docs/converloop-portable-backup-v1.schema.json	Public portable-backup JSON schema

Local credentials, editor launch settings, generated builds, and private planning notes are intentionally ignored and should never be committed.

How Converloop is built

Converloop uses Electron, React 19, TypeScript, Vite, SQLite (Node's built-in node:sqlite) with Drizzle, Zod, Vitest, and Biome.

Its architectural rule is simple:

Conversation agents read Markdown; tutor agents read SQLite. Code writes SQLite; maintenance agents write Markdown. LLMs observe and propose—code owns the ledger.

Document	Contents
docs/design.md	Current product shape, core design principles, and development guidance
docs/converloop-portable-backup-v1.schema.json	Portable learning-data exchange schema

This keeps mastery_key stable across sentences and makes learning-state changes traceable and testable. See docs/design.md for the product shape and long-term design principles. Implementation details live in code and tests.

Contributing

Contributions are welcome. Keep changes small and tied to the learning loop; prompt, schema, migration, and provider details are governed by code and tests. Before opening a pull request, run:

pnpm check
pnpm test

External contributions are accepted under the Contributor License Agreement.

Before opening a pull request, also check that no credentials, local absolute paths, signing certificates, generated release/ output, or private planning notes are included in the diff.

License

Converloop is dual-licensed:

• Open source — GNU AGPL-3.0-or-later. You may use, modify, and distribute the open-source project under the AGPL.
• Commercial license. A separate proprietary license is available for uses that cannot comply with the AGPL, such as closed-source distribution. See COMMERCIAL.md.