Content
<p align="center">
<img src="frontend/src/assets/sage-thinking-fallback.png" width="112" alt="Sage" />
</p>
<h1 align="center">Sage</h1>
<p align="center">
<strong>Personal AI Learning Companion</strong><br />
Connect personal projects, knowledge sources, and real-world practices into a traceable, verifiable, and sustainable growth path.
</p>
<p align="center">
<a href="https://github.com/ZeroMadLife/sage-agent/actions/workflows/quality.yml"><img src="https://github.com/ZeroMadLife/sage-agent/actions/workflows/quality.yml/badge.svg" alt="Sage Quality" /></a>
<a href="https://github.com/ZeroMadLife/sage-agent/actions/workflows/backend-quality.yml"><img src="https://github.com/ZeroMadLife/sage-agent/actions/workflows/backend-quality.yml/badge.svg" alt="Backend Quality" /></a>
<img src="https://img.shields.io/badge/Python-3.12+-3776AB" alt="Python 3.12+" />
<img src="https://img.shields.io/badge/Vue-3-42B883" alt="Vue 3" />
<img src="https://img.shields.io/badge/License-MIT-111827" alt="MIT License" />
</p>
Sage is a locally-prioritized personal AI learning and practice workstation. It uses conversations as the entry point, connecting code repositories, Markdown/Obsidian knowledge, model providers, skills, and MCP tools into a recoverable Chat Harness.
Coding is not removed but becomes Sage's **Practice Engine**: used for reading source code, modifying code, running tests, and verifying understanding. Knowledge is responsible for source ingestion, Wiki proposals, retrieval, and citation; all operations that may change long-term knowledge, code, or external systems retain evidence and human control points.
> **Current Status**: The project is rapidly developing, suitable for local use, architecture research, and controlled private testing. One-click deployment of production servers is still under construction; do not expose Vite/FastAPI development ports directly to the public network.
## Tool List
| Surface | Function | Current Status |
| --- | --- | --- |
| **Today** `/#/assistant` | Personal entry, recent conversations, knowledge status, and next-step suggestions | Delivered |
| **Practice** `/#/coding/session/:id` | Code reading, editing, testing, approval, diff, and execution evidence | Delivered, Harness 2.0 enabled by default |
| **Knowledge** `/#/knowledge` | Source ingestion, knowledge graph, Wiki proposals, retrieval, and citation | Delivered local workflow |
| **Evolution Record** `/#/evolution` | Summarizes Learning Evidence and controlled evolution proposals | Stage entry, under construction |
| **Public Homepage** `/#/public` | Future release of filtered public material packages | Stage entry, not yet open for release |
| **Settings** `/#/settings/:section` | Provider, Skills, MCP, Memory, Context, and runtime configuration | Delivered |
## What Can Be Done Now
### A Recoverable Chat Harness
- WebSocket streaming output with durable timeline; continues playback and recovery after refresh or disconnection.
- Unified presentation of planning, reasoning, tool, approval, reply, and terminal stages.
- Context budget, automatic compression, checkpoint, run trace, and long tool result artifact.
- Same Harness reused for Assistant, Knowledge, and Coding, without rewriting Agent loop for each page.
### Controlled Practice Engine
- `list_files`, `read_file`, `search`, `run_shell`, `write_file`, `patch_file`, etc. workspace tools.
- Path containment, fresh-read, permission mode, dangerous command approval, and write diff.
- Plan Mode, Todo, Skills, MCP, sub-agents, and interruptible execution.
- Harness 2.0 enables new sessions by default; production/staging only allows enablement with configured Container Sandbox.
- Container Sandbox supports read-only rootfs, network disable, resource limits, controlled workspace mount, and exit cleanup.
### Traceable Knowledge Workflow
- Ingests Markdown, Obsidian, and controlled file sources, retaining immutable source snapshots.
- Asynchronous tasks, failure recovery, Wiki proposals, approval/rejection/rollback, and version evidence.
- Sparse/dense hybrid retrieval, RRF, stable citation, and context budget.
- Conversations can propose Note, Wiki, or Memory Proposal but will not silently overwrite verified knowledge.
### Long-Term Engineering Loop
- Provider configuration, key encryption storage, capability detection, and usage recording.
- GitHub OAuth + invite-only cloud identity foundation and session/workspace ownership boundary.
- Loop Engineer scans low-risk issues in independent worktree; only strict Tier A frontend minor repairs allow automatic merging.
- Feishu cc-connect as external development channel, continuing to comply with repository Git, testing, and deployment access control.
## Architecture
```text
Browser / Mobile Web
-> Vue 3 + Pinia
-> REST + WebSocket
-> FastAPI
├─ Assistant Home
├─ Chat Harness
│ ├─ durable timeline / checkpoint / context compaction
│ ├─ middleware / skills / MCP / subagents
│ └─ approval / evidence / artifact / usage
├─ Practice Engine
│ ├─ workspace + Git + file tools
│ └─ local workspace | container sandbox
├─ Knowledge Engine
│ ├─ source snapshots / ingest jobs / Wiki proposals
│ └─ sparse + dense retrieval / RRF / citations
└─ Cloud Control Plane
├─ GitHub OAuth / invite / ownership
└─ encrypted model provider settings
State and infrastructure
├─ PostgreSQL + pgvector
├─ Redis Streams
├─ SQLite durable runtime stores
└─ Git-backed workspace and knowledge artifacts
```
The core Harness is maintained as an independent Python package in `packages/sage_harness/`. The Sage product layer is responsible for adapting user identity, workspace, Knowledge, Sandbox, and frontend timeline to Harness's stable ports.
## Quick Start
### Environment Requirements
- Python 3.12+
- Node.js 20+
- Docker Engine + Docker Compose v2
- macOS, Linux, or Windows WSL
### 1. Get Code
```bash
git clone https://github.com/ZeroMadLife/sage-agent.git
cd sage-agent
```
### 2. Install Dependencies
```bash
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt
cd frontend
npm install
cd ..
```
### 3. Configure Local Environment
```bash
cp .env.example .env
```
Configure at least one available model provider. For example:
```dotenv
DEEPSEEK_API_KEY=your_key
```
`.env`, Provider key, OAuth secret, and runtime credentials should not be submitted to Git.
### 4. Start
```bash
bash scripts/dev.sh
```
The script will start PostgreSQL/pgvector, Redis, FastAPI, and Vite:
- Sage Web: `http://127.0.0.1:5173`
- API: `http://127.0.0.1:8000`
- Health: `http://127.0.0.1:8000/health`
To enable Knowledge persistent tasks, execute:
```bash
python -m db.migrations
```
See [Getting Started](docs/GETTING-STARTED.md) for more complete environment variables, worktree collaboration, and Knowledge Source configuration.
## Common Verification
```bash
# Backend, type, and basic quality gate
bash scripts/check.sh
# Coding/Harness oriented regression
pytest tests/core/coding tests/core/harness tests/harness tests/api/test_coding_routes.py -q
# Frontend testing and production build
cd frontend
npm run test -- --run
npm run build
```
GitHub Actions will execute backend, frontend, Ruff, mypy, and production build gate again.
## Repository Structure
```text
sage-agent/
├── api/ # FastAPI routes, WebSocket, and cloud control plane
├── core/
│ ├── coding/ # Practice Engine, persistence, tools, and runtime coordination
│ ├── harness/ # Sage to universal Harness adaptation layer
│ ├── knowledge/ # Ingestion, graph, retrieval, Wiki, and learning evidence
│ ├── cloud/ # Identity, Workspace, and Provider settings
│ └── loop_harness/ # Loop Engineer controller
├── packages/sage_harness/ # Reusable Chat Harness 2.0 package
├── frontend/ # Vue 3 product interface
├── agents/ # travel-planning domain Agent and LangGraph
├── mcp_servers/ # Gaode, weather, scenic spot MCP servers
├── evals/ # Harness, Knowledge, and domain evaluation
├── tests/ # Backend, API, contract, and integration testing
├── docs/ # Product design, implementation plan, Review, and operation documents
└── docker-compose.yml # Local PostgreSQL/pgvector + Redis
```
## Real Boundaries
- Current `docker-compose.yml` only orchestrates local PostgreSQL/pgvector and Redis, not a production deployment stack.
- Evolution and Public Profile are still stage entries, not described as completed growth systems or public agents.
- GitHub OAuth, ownership, and Provider encryption have backend foundation, but public network exposure still requires HTTPS, production secrets, invite-only configuration, rate limiting, backup, and recovery drill.
- Local `local_workspace` allows tools to act on specified repositories; public network environments must use Container Sandbox, not exposing host workspaces directly to browser tasks.
- Original TourSwarm travel planning capability is retained as the first domain Skill and multi-constraint benchmark, not the main product entry.
## Project Documents
- [Sage V7 Product Design](docs/superpowers/specs/2026-07-15-sage-v7-personal-assistant-knowledge-evolution-design.md)
- [Chat Harness 2.0 Design](docs/superpowers/specs/2026-07-16-sage-chat-harness-v2-design.md)
- [Loop Engineer](docs/loop-harness/README.md)
- [Development Environment Guide](docs/GETTING-STARTED.md)
- [Development Collaboration Agreement](AGENTS.md)
## Branches and Contributions
- `main`: versions that pass complete release gate.
- `dev/sage-v7`: current integration branch.
- Features and fixes: completed in independent worktree `codex/*` branches, merged into development branch via PR.
Please keep single responsibility before submission, attach Chinese PR description, and provide matching test, build, and `git diff --check` evidence.
## License
MIT
Connection Info
You Might Also Like
No recommendations available