ino-agent

Local-first AI workspace for students, developers, and researchers.

ino-agent combines a tree-structured AI chat, long-term memory, local knowledge search, project generation, safe command execution, agent task planning, and visual learning blocks inside one Tauri desktop app.

---

Important

ino-agent is an active release-candidate project. It is built for local development, study, research, and internal dogfood. Public macOS distribution still needs Developer ID signing and notarization.

The app stores user data locally. Do not publish local SQLite databases, .env files, API keys, command logs, .app bundles, or .dmg artifacts from your own machine.

About

Most AI chats are a single long timeline. That works for quick questions, but breaks down when a student explores multiple explanations, a developer branches into implementation options, or a researcher needs to keep sources, decisions, commands, and memory connected.

ino-agent treats the workspace as a tree:

1. A root is a topic, project, lecture, or research thread.
2. Each node is a stable point in the conversation.
3. Child nodes are alternative branches of reasoning.
4. The agent can use local memory, indexed knowledge, project files, and safe tools.
5. Progress is persisted so work can continue after restart.

The goal is not just to answer prompts. The goal is to help users build, learn, debug, search, remember, and continue work locally.

Who It Is For

Students

• Understand lectures, PDFs, notes, and course material.
• Get explanations with math, tables, matrices, vectors, charts, Mermaid diagrams, and graph steps.
• Generate quizzes and step-by-step examples.
• Keep track of weak topics, mistakes, preferences, and exam preparation tasks.
• Search across local notes and past memory.

Developers

• Create starter projects from scratch.
• Run build, test, and run commands from the app.
• Ask the agent to inspect a project and propose next tasks.
• Break a goal into PRD, specs, and atomic tasks.
• Keep command execution visible and approval-based.

Researchers

• Build a local research workspace.
• Index local source files and search them with scores and chunks.
• Keep decisions, source notes, hypotheses, and feedback in memory.
• Ask questions with source-grounded answers and related memory.

Features

Tree Chat

• Multiple chat trees.
• Branches from any selected node.
• Leaf-only writing to preserve old reasoning paths.
• AI branch planning for broad or multi-part prompts.
• Streaming assistant responses.
• Attachment flow with local PDF text extraction.

Long-Term Memory

• Shared memory across chats.
• Memory items with title, description, target, source type, tags, importance, confidence, stability, and kind.
• Automatic memory extraction.
• Decision log explaining why something was remembered or skipped.
• Memory edit, delete, merge, feedback, and graph debug view.
• Review queue for duplicates, stale items, low-confidence items, and negative feedback.
• Memory export/import as JSON.
• "Why remembered" visibility from the decision log.

Knowledge Search / RAG

• Local source indexing.
• Knowledge chunks with SQLite metadata.
• Local hashed embedding MVP.
• Hybrid scoring: vector score, keyword score, feedback score, and recency.
• Lightweight reranking.
• Watched paths and reindex controls.
• Retrieval trace in answers.
• Search page with answer, sources, chunks, scores, targets, offsets, open-source actions, and related memory.

Project Wizard

Create a new workspace from inside the app.

Supported project types:

• Python CLI
• Python notebook/research
• C++/CMake
• Rust
• TypeScript/React
• Tauri app
• study notes
• research workspace

Generated projects include README, .gitignore, build scripts, tests, starter code, and project commands. After creation, the user can open the folder, build, run, test, or ask the agent for next steps.

Agent Tasks

The agent can work through a goal as persisted tasks:

• create a PRD;
• split it into specs;
• split specs into atomic tasks;
• execute one task at a time;
• store result, error, trace, and progress;
• continue after app restart.

This is the base for a future "complete the whole project" mode.

Safe Terminal

ino-agent can run workspace commands with safety rules:

• workspace-scoped current directory;
• timeout and max output limits;
• command history;
• repeat command;
• command output in the UI;
• build/test/run diagnostics.

Commands that can delete, overwrite, install packages, access the network, push to Git, or run an unknown binary require explicit approval.

Visual Learning Blocks

Assistant messages can render more than plain Markdown:

• Markdown and GFM tables;
• KaTeX math;
• quiz blocks;
• matrix blocks;
• vector blocks;
• chart blocks;
• proof blocks;
• source lists;
• step examples;
• Mermaid diagrams;
• graphsteps with previous/next navigation.

Render blocks are covered by Playwright desktop/mobile screenshot QA.

Tool and Context Traces

The UI can show:

• tool traces;
• command traces;
• retrieval traces;
• memory decisions;
• permission profile used by the agent.

The user can see what the agent used and what it did.

How It Works

1. The user creates a chat tree, project, or research workspace.
2. The app stores chat state, memory, settings, command history, and task progress in local SQLite.
3. Local sources can be indexed into knowledge chunks.
4. The agent builds context dynamically from chat, memory, knowledge, render contracts, and tool traces.
5. The user can ask questions, create projects, run commands, search sources, or start an agent task run.
6. Dangerous commands are gated by explicit approval.
7. Memory review keeps long-term memory understandable and maintainable.

Privacy

ino-agent is local-first.

Default macOS database path:

~/Library/Application Support/ino-agent/ino-agent.sqlite3

The local database may contain:

• chat trees and messages;
• model endpoint, model name, and API key;
• memory items and memory decisions;
• indexed source metadata;
• watched local paths;
• command history and output;
• agent task progress.

Network access is needed only for configured model calls or user-approved network commands. See Privacy for details.

Tech Stack

• Frontend: React 18, TypeScript, Vite, Tailwind CSS.
• Desktop shell: Tauri 2.
• Backend: Rust.
• Storage: SQLite through rusqlite.
• Graph UI: @xyflow/react.
• Markdown: react-markdown, remark-gfm, remark-math, rehype-katex.
• Diagrams: Mermaid.
• QA: Playwright screenshot tests.

Installation and Development

ino-agent is a Tauri 2 desktop application. Build on the operating system you intend to run it on: native installers are not normally cross-compiled by the default Tauri toolchain.

Requirements

All platforms need:

• Node.js 20 LTS or newer and npm;
• Rust stable via rustup;
• an OpenAI-compatible chat-completions endpoint and API key for model-backed features.

Platform-specific requirements:

• macOS 10.15+: Xcode Command Line Tools (xcode-select --install). A DMG build also needs python3, codesign, and hdiutil; the last two are provided by macOS.

• Linux: WebKitGTK 4.1, GTK, AppIndicator, librsvg, OpenSSL, patchelf, file, and a C/C++ toolchain. On Ubuntu/Debian, the CI-equivalent setup is:

  sudo apt update
  sudo apt install -y libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev \
    libgtk-3-dev libxdo-dev libssl-dev patchelf build-essential file

• Windows 10/11: Visual Studio Build Tools with Desktop development with C++, Rust's stable-msvc toolchain, and Microsoft Edge WebView2. WebView2 is normally already installed. MSI packaging may also require the Windows optional VBScript feature.

See the official Tauri prerequisites for other Linux distributions and current platform details.

Install and run

git clone github.com/alimak4v/ino_agent
cd ino_agent
npm ci
npm run tauri:dev

The first run downloads Rust and npm dependencies and may take several minutes. Open Settings in the app to save the endpoint, model, API key, language, and theme. Credentials and user data remain local; do not commit databases or secrets.

For frontend-only work, use npm run dev. This does not provide native file access, SQLite, terminal commands, or other Tauri invoke features. Use npm run dev:render-smoke for the deterministic QA fixture.

Validation and Tests

npm run build                                      # TypeScript check + Vite production build
cargo check --manifest-path src-tauri/Cargo.toml  # Rust compile check
cargo clippy --manifest-path src-tauri/Cargo.toml --all-targets
cargo test --manifest-path src-tauri/Cargo.toml
npm run qa:render-screenshots                     # Playwright desktop + mobile screenshots

Playwright writes ignored output to test-results/; inspect failures and traces before changing expectations. Screenshot coverage includes responsive layout, math, diagrams, charts, and graph blocks.

Packaging and Release Builds

The portable Tauri command works on macOS, Linux, and Windows:

npm run tauri:build

Artifacts are written under src-tauri/target/release/bundle/ (for example, macOS .app/.dmg, Linux .deb/.AppImage, and Windows .msi/.exe, depending on installed platform tooling).

For the internal macOS release-candidate flow, run on macOS:

bash build_macos.sh

It creates dist/ino-agent.app, dist/ino-agent-mac.dmg, and a SHA-256 checksum. The script uses ad-hoc signing unless APPLE_SIGNING_IDENTITY is set. Public macOS distribution still requires Developer ID signing and notarization. Release artifacts, dist/, and build caches are ignored and must not be committed.

Clean rebuild

If stale frontend or Rust output causes a problem, remove only generated directories and reinstall:

rm -rf dist src-tauri/target node_modules
npm ci
npm run tauri:build

On Windows, remove the same directories from PowerShell or delete them in Explorer.

Release Status

Done for release MVP:

• Project wizard.
• Agent loop with tasks/progress.
• Safe command runner UI.
• Search page with sources.
• Memory cleanup/review.
• Render screenshot QA.
• Stable macOS internal RC build.
• First-run onboarding.
• Release docs.

Still open before a public release:

• Manual dogfood on the demo scenarios.
• Developer ID signing and notarization.
• More tests for DB migrations, command safety, agent loop, crash recovery, and memory quality.
• Better OCR, PDF extraction, DOCX/HTML/audio ingestion, and code-aware indexing.

Documentation

• Quickstart
• Install
• Privacy
• Release checklist
• Release technical scope
• Demo scenarios
• Render QA

Repository Map

src/
  App.tsx                         main desktop UI orchestration
  components/
    ChatPanel.tsx                 chat composer and messages
    TreeCanvas.tsx                tree navigation canvas
    ProjectWizardPanel.tsx        project generator UI
    AgentTasksPanel.tsx           persisted agent task UI
    TerminalPanel.tsx             safe command runner UI
    SearchPanel.tsx               local memory/knowledge search
    MemoryPanel.tsx               memory graph, review, import/export
    KnowledgePanel.tsx            indexing and watched paths
    MarkdownMessage.tsx           markdown, math, rich render blocks
  lib/api.ts                      typed frontend wrapper over Tauri commands

src-tauri/src/
  lib.rs                          Tauri commands and agent orchestration
  store.rs                        SQLite schema, migrations, memory, search, tasks
  api.rs                          OpenAI-compatible chat completions via curl
  project.rs                      project templates and project command runner
  terminal.rs                     safe terminal command assessment and execution
  local_embedding.rs              local hashed embedding MVP
  retrieval_context.rs            retrieval context and trace formatting

License

No public license has been selected yet.