179 lines
7.0 KiB
Markdown
179 lines
7.0 KiB
Markdown
# OpenNexus
|
|
|
|
[简体中文](README.zh-CN.md) | **English**
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
OpenNexus is a local-first AI notebook and knowledge workspace. It combines Markdown vaults, hybrid retrieval, grounded chat, auditable agents, media-to-notes workflows, extensions, and optional multi-device synchronization in one desktop application.
|
|
|
|
> Current release: **0.5.2-alpha1**. Back up important vaults before upgrading an alpha build.
|
|
|
|
## Highlights
|
|
|
|
- **Course recordings to structured notes** — transcribe real audio or video, review timestamped text, and generate knowledge-point notes with code blocks, Mermaid diagrams, formulas, and function plots when appropriate.
|
|
- **Personal planning agents** — create goal-oriented agents, generate plans and tasks, control tool permissions, and inspect execution traces.
|
|
- **Local-first knowledge base** — edit Markdown, manage attachments, and combine SQLite FTS5, vector retrieval, reciprocal-rank fusion, and reranking.
|
|
- **Provider choice** — connect OpenAI, Anthropic, Ollama, DeepSeek, and OpenAI-compatible endpoints without storing credentials in the WebView.
|
|
- **Extensible workspace** — install Skills, Plugins, themes, and MCP integrations with explicit permissions and trust review.
|
|
- **Portable output** — export notes to PDF, HTML, and DOCX; workspace images use content-addressed relative paths.
|
|
- **Optional synchronization** — sync notes and attachments between devices with conflict preview, revision history, and device revocation.
|
|
|
|
## Architecture
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
UI[Vue 3 desktop UI] --> HOST[Tauri / Rust host]
|
|
HOST --> VAULT[Local Markdown vault]
|
|
HOST --> CORE[FastAPI AI Core]
|
|
CORE --> INDEX[(SQLite / FTS5 / sqlite-vec)]
|
|
CORE --> MODEL[Local or remote models]
|
|
CORE --> EXT[Skills / Plugins / MCP]
|
|
HOST <--> SYNC[Optional Sync Server]
|
|
SYNC --> DB[(PostgreSQL)]
|
|
SYNC --> OBJ[S3-compatible storage]
|
|
COMMUNITY[Community prototype] --> EXT
|
|
```
|
|
|
|
The desktop host owns local filesystem access, credentials, process supervision, and privileged extension operations. The AI Core runs as a separately supervised process over an authenticated local channel. The Sync Server and community prototype are optional components. The Gitea release mirror keeps all components in one monorepo; the public GitHub projects are maintained separately.
|
|
|
|
## Repository layout
|
|
|
|
| Path | Purpose |
|
|
| --- | --- |
|
|
| `frontend/` | Vue 3 UI and Tauri/Rust desktop host |
|
|
| `backend/` | FastAPI AI Core, retrieval, agents, media processing, and export |
|
|
| `server sync/` | Sync v1 server and its Vue management console |
|
|
| `community-server/` | Community catalog and moderation prototype |
|
|
| `scripts/` | Build, acceptance, and release automation |
|
|
| `tools/` | Local development and packaging utilities |
|
|
|
|
## Public repositories
|
|
|
|
| Component | GitHub repository |
|
|
| --- | --- |
|
|
| Desktop application and AI Core | [KiriAky107/OpenNexus](https://github.com/KiriAky107/OpenNexus) |
|
|
| Sync Server | [KiriAky107/Sync-for-OpenNexus](https://github.com/KiriAky107/Sync-for-OpenNexus) |
|
|
| Community prototype | [KiriAky107/Community-for-OpenNexus](https://github.com/KiriAky107/Community-for-OpenNexus) |
|
|
|
|
The Gitea distribution repository remains a monorepo so a release can be built and demonstrated from one revision. GitHub keeps the three independently deployable components in separate repositories.
|
|
|
|
## Install the desktop app
|
|
|
|
1. Download `OpenNexus_0.5.2-alpha1_x64-setup.exe` from the [v0.5.2-alpha1 release](https://gitea.kronecker.cc/Kronecker/NotesAgentic/releases/tag/v0.5.2-alpha1).
|
|
2. Verify the published SHA-256 checksum.
|
|
3. Run the installer and start OpenNexus from the Start menu.
|
|
4. Select or create a Markdown vault.
|
|
5. Configure a local or remote model under **Settings → Model providers**.
|
|
|
|
The installer contains no user vault, downloaded model weights, CUDA runtime, or preinstalled community package. Existing configuration and indexes remain under `%APPDATA%\cc.kronecker.notesagent` during an in-place upgrade.
|
|
|
|
## Development
|
|
|
|
### Requirements
|
|
|
|
| Tool | Version |
|
|
| --- | --- |
|
|
| Node.js | 22+ |
|
|
| pnpm | 10.28.0 |
|
|
| Python | 3.12+ |
|
|
| uv | 0.9.24 |
|
|
| Rust | stable |
|
|
|
|
Install dependencies:
|
|
|
|
```powershell
|
|
cd backend
|
|
uv sync --frozen
|
|
|
|
cd ../frontend
|
|
corepack enable
|
|
corepack prepare pnpm@10.28.0 --activate
|
|
pnpm install --frozen-lockfile
|
|
```
|
|
|
|
Run the web development stack:
|
|
|
|
```powershell
|
|
# Terminal 1: AI Core
|
|
cd backend
|
|
uv run python scripts/dev-server.py
|
|
|
|
# Terminal 2: frontend
|
|
cd frontend
|
|
pnpm dev
|
|
```
|
|
|
|
Build the Windows desktop application:
|
|
|
|
```powershell
|
|
cd frontend
|
|
pnpm desktop:build
|
|
```
|
|
|
|
## Tests
|
|
|
|
```powershell
|
|
# Backend
|
|
cd backend
|
|
uv run pytest
|
|
|
|
# Frontend
|
|
cd ../frontend
|
|
pnpm test
|
|
pnpm type-check
|
|
pnpm build
|
|
|
|
# Rust host
|
|
cd src-tauri
|
|
cargo fmt --check
|
|
cargo test --all-targets --features desktop
|
|
cargo clippy --all-targets --features desktop -- -D warnings
|
|
|
|
# Sync Server
|
|
cd "../../../server sync"
|
|
uv sync --frozen
|
|
uv run pytest
|
|
```
|
|
|
|
## Run the Sync Server
|
|
|
|
The recommended deployment uses Docker Compose with PostgreSQL and S3-compatible object storage:
|
|
|
|
```powershell
|
|
cd "server sync"
|
|
Copy-Item .env.example .env
|
|
docker compose up -d --build
|
|
```
|
|
|
|
Use independent production secrets, TLS termination, process supervision, and regular backups. Plain HTTP options are intended only for isolated demonstrations and local testing.
|
|
|
|
## Security and privacy
|
|
|
|
- Vault content stays local unless the user explicitly enables a remote model, synchronization, or another network integration.
|
|
- Provider credentials are stored by the desktop credential vault and are not persisted in frontend `localStorage`.
|
|
- Extension permissions, network access, and privileged tool calls are reviewed before authorization.
|
|
- Logs and bug reports must not contain vault text, access tokens, provider keys, or personal information.
|
|
- Only install Skills, Plugins, themes, and MCP servers from sources you trust.
|
|
|
|
Please report security issues privately to the repository maintainers instead of opening a public issue with sensitive details.
|
|
|
|
## Contributing
|
|
|
|
Use locked dependencies, keep frontend/backend contracts synchronized, and run the relevant test suites before submitting a change. Commit messages follow Conventional Commits, for example:
|
|
|
|
```text
|
|
feat(sync): add device revocation
|
|
fix(export): restore PDF rendering in packaged builds
|
|
test(agent): cover interrupted task recovery
|
|
```
|
|
|
|
OpenNexus is currently an alpha project. Issues should include the application version, operating system, reproduction steps, and redacted correlation IDs.
|
|
|
|
## License
|
|
|
|
OpenNexus project code is licensed under the [MIT License](LICENSE). Bundled models, libraries, fonts, icons, and other third-party components remain subject to their own licenses and notices; the project MIT License does not replace those terms.
|