# Continuum

**OS de engenharia com IA, local-first** — memória persistente para agentes via MCP.

> One memory. Every agent. Continuous engineering.

[English summary](#english-summary) · [Privacidade](PRIVACY.md) · Licença [MIT](LICENSE)

## O que é

O Continuum guarda decisões, contexto de projeto e estado útil para agentes de IA (Cursor e outros) num banco **SQLite local**. Expõe:

- CLI `continuum` (init, doctor, projetos, memória, git read-only)
- Servidor **MCP stdio** para o agente chamar ferramentas de memória e git

Tudo roda na sua máquina. Sem cloud Continuum, sem telemetria.

## Local-first e privacidade

- **Sem banco na nuvem** — dados em `~/.continuum/` (override: `CONTINUUM_HOME`)
- **Zero telemetria** — o Continuum não phone-home
- **Offline por padrão** — nada sai da máquina sem ação explícita sua
- **Cursor / LLM** — o modelo e a conta do Cursor (ou outro host) são **separados** do Continuum; o Continuum só oferece ferramentas MCP locais

Detalhes: [PRIVACY.md](PRIVACY.md).

```text
~/.continuum/
  config.toml
  continuum.db
  logs/
  cache/
  backups/
```

## Estado do projeto

**Já funciona (MVP + roadmap A–G + polish):**

- SQLite local + CRUD de memória + busca lexical (FTS5)
- Embeddings locais via Ollama + vector store SQLite (BLOB) + busca híbrida
- Indexador de repositório (`continuum index` / `continuum project index`)
- Context assembler (`project_context` com seções compactas)
- Knowledge graph em SQLite (entities / relationships) + CLI/MCP + UI com filtros
- Política de branch/commit (Conventional Commits, quality gates; sem force push)
- GitHub PRs (token via `GITHUB_TOKEN` / keyring; merge só com `--approve`)
- Handoff de sessão + auto-detect DECISION/CONSTRAINT + supersede em conflito
- Explorer web (`apps/web` Vue+Vite + `continuum serve` em `:8787`)
- App desktop Windows (`continuum desktop` / atalho com ícone)
- Projetos + CLI e MCP stdio + logging JSON local

**Adiado:** Neo4j, sync multi-dispositivo (ver abaixo), merge automático em main.
Publicação PyPI está preparada (`uv build` / `uv publish`) e exige token.

## Requisitos

- Python 3.12+
- [uv](https://docs.astral.sh/uv/) (desenvolvimento / clone)
- Git no `PATH` (ferramentas git)

## Instalação

### Usuário final (quando publicado no PyPI)

```bash
pip install continuum
# ou
uv tool install continuum
```

Depois o comando `continuum` fica no PATH.

### Desenvolvimento / clone (agora)

```bash
git clone https://github.com/matheusxdev/continuum.git
cd continuum
uv sync --extra dev
```

Instalação editável a partir do git (sem clonar manualmente):

```bash
uv pip install "git+https://github.com/matheusxdev/continuum.git"
# ou
pip install "git+https://github.com/matheusxdev/continuum.git"
```

## Embeddings com Ollama (recomendado)

1. Instale e inicie o [Ollama](https://ollama.com/).
2. Puxe um modelo de embedding:

```bash
ollama pull nomic-embed-text
```

3. Em `~/.continuum/config.toml`:

```toml
embedding_provider = "ollama"
embedding_model = "nomic-embed-text"
ollama_base_url = "http://127.0.0.1:11434"
```

4. Confirme: `continuum doctor` (Ollama + Embedding model OK).
`memory_save` passa a gerar embeddings; `memory search --mode hybrid|semantic` usa o vetor.
Se o Ollama estiver offline, a busca degrada para lexical sem falhar.

## Quick start

```bash
uv run continuum init
uv run continuum doctor
uv run continuum project add .
uv run continuum memory save "Decidimos continuar com Vue + Vite" --type DECISION
uv run continuum memory search "Vue"
uv run continuum index
uv run continuum git status
uv run continuum project context
```

Com o pacote já no PATH (`pip install` / `uv tool install`):

```bash
continuum init
continuum doctor
continuum project add .
continuum mcp
```

## Cursor — configuração MCP

### Recomendado (pacote instalado no PATH)

```json
{
  "mcpServers": {
    "continuum": {
      "command": "continuum",
      "args": ["mcp"]
    }
  }
}
```

### Desenvolvimento com uv (caminho do clone)

Substitua o diretório pelo caminho absoluto do repositório na sua máquina:

**Windows**

```json
{
  "mcpServers": {
    "continuum": {
      "command": "uv",
      "args": ["run", "--directory", "C:/path/to/continuum", "continuum", "mcp"]
    }
  }
}
```

**macOS / Linux**

```json
{
  "mcpServers": {
    "continuum": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/continuum", "continuum", "mcp"]
    }
  }
}
```

Há um exemplo em [`.cursor/mcp.json`](.cursor/mcp.json) no repositório (forma PATH).

### Ferramentas MCP

| Tool | Modo | Descrição |
|------|------|-----------|
| `memory_save` | mutating | Persistir memória |
| `memory_search` | read-only | Busca híbrida (lexical + semântica) |
| `memory_semantic_search` | read-only | Só vetor (Ollama) |
| `memory_get` / `memory_update` / `memory_delete` / `memory_recent` | — | CRUD |
| `memory_supersede` | mutating | Marcar memória como SUPERSEDED |
| `project_*` / `project_context` | — | Projetos + contexto em seções |
| `git_*` / `branch_*` / `commit_*` | — | Git seguro (sem force push) |
| `entity_*` / `graph_traverse` | read-only | Knowledge graph |
| `pr_*` / `push_branch` | mutating | GitHub PRs (merge exige `approve`) |
| `session_handoff` | read-only | Resumo de handoff |

## Explorer web (mínimo)

```bash
cd apps/web && npm install && npm run build
uv run continuum serve   # http://127.0.0.1:8787
# ou só o front em dev:
cd apps/web && npm run dev   # proxy /api → :8787
```

## App desktop (Windows)

Janela dedicada (WebView2) com a mesma UI de `http://127.0.0.1:8787` — sem depender de uma aba do navegador, e pode ir para a barra de tarefas.

```powershell
# 1) Build da UI (se ainda não tiver apps/web/dist)
cd apps/web; npm install; npm run build; cd ../..

# 2) Dependência pywebview + abrir
uv sync --extra desktop
uv run continuum desktop
# ou:
.\scripts\continuum-desktop.ps1
```

O comando sobe `continuum serve` em segundo plano **só se** a porta `8787` estiver livre. Ao fechar a janela, encerra apenas o servidor que ele mesmo iniciou.

### Fixar na barra de tarefas

```powershell
# Gera assets/continuum.ico (se faltar) e cria Continuum.lnk na Área de trabalho
.\scripts\continuum-desktop.ps1 -InstallShortcut
# Também no Menu Iniciar:
.\scripts\continuum-desktop.ps1 -InstallShortcut -StartMenuAlso
```

Depois abra o atalho uma vez e, na barra de tarefas, botão direito → **Fixar na barra de tarefas**.
Ícone: `assets/continuum.ico`.

Requisito: [WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2/) (já presente na maioria dos Windows 10/11).

## Indexar repositório

Indexa README / markdown / código (respeita denylist: `.env`, `node_modules`, `.git`, secrets), grava chunks como memórias `PROJECT_CONTEXT` e gera embeddings quando Ollama está ativo. Incremental por hash.

```bash
uv run continuum index
uv run continuum project index
uv run continuum index --force   # reindexar tudo
```

## Sync multi-dispositivo (adiado)

Sync entre máquinas **não** entra no escopo atual: quebraria o modelo local-first (sem cloud Continuum, sem telemetria). Continuidade entre PCs fica para um desenho futuro explícito (export/import opt-in ou sync peer-to-peer), nunca automático. Use backup de `~/.continuum/` se precisar mover dados.

## Layout do código

```text
src/continuum/
  apps/cli/          CLI (Typer)
  apps/mcp/          MCP stdio
  apps/desktop/      Shell pywebview (Windows)
  apps/webapi/       API local do explorer
  core/memory/       Memória + hybrid search
  core/embeddings/   Ollama / null providers
  core/vector/       SQLite BLOB vector store
  core/graph/        Knowledge graph
  core/context/      Context assembler
  core/indexer/      Repository indexer
  core/git/          Git + commit policy + quality gates
  core/github/       GitHub PRs
  core/handoff/      Handoff + auto-type + supersede
  database/          Schema + migrations
  config/            Paths, settings, logging
apps/web/            Vue + Vite explorer
assets/              continuum.ico
scripts/             Launchers (desktop.ps1 / .bat / generate_ico)
docs/                ADRs
```

## Testes e build

```bash
uv sync --extra dev
uv run pytest
uv build
```

Artefatos em `dist/` (wheel + sdist).

## Publicar no PyPI (quando tiver token)

Não publique sem `UV_PUBLISH_TOKEN` / credenciais configuradas.

```bash
uv build
uv publish
```

Alternativa com Twine:

```bash
uv build
uv run twine upload dist/*
```

Crie um token em https://pypi.org/manage/account/token/ e use TestPyPI primeiro se preferir:

```bash
uv publish --publish-url https://test.pypi.org/legacy/
```

## Spec / roadmap

- [CONTINUUM_SPEC.md](CONTINUUM_SPEC.md) — especificação original
- [CONTINUUM_COMPLETA.md](CONTINUUM_COMPLETA.md) — visão completa / roadmap

---

## English summary

Continuum is a **local-first AI Engineering OS**: persistent agent memory over **local SQLite** (`~/.continuum`), with a Typer CLI and MCP stdio server for Cursor and other hosts. **No Continuum cloud DB, no telemetry.** The Cursor/LLM provider is separate from Continuum itself.

**Install (when on PyPI):** `pip install continuum`  
**Dev now:** `git clone` → `uv sync --extra dev` → `uv run continuum init`

See [PRIVACY.md](PRIVACY.md) for privacy guarantees. MIT licensed.