Getting Started

Previously is an agent we built ourselves — one kernel, two ways to run it:

• Deploy on Vercel (recommended) — the full form: every conversation turn is a durable run that survives dropped connections; reachable from anywhere, including your phone's browser; every capability switched on. Memory lives in your own private GitHub repository — no database.
• Run locally (npm) — the optional path when you don't want to deploy anything: one npm command, memory on your local disk. Feature-for-feature the same as the cloud.

Both paths are walked through on this page, the recommended one first.

Path one: deploy on Vercel (recommended)

Three steps, about ten minutes:

1. Create the private repo. On previously-lab/agent, click Use this template to create your copy, and make it private — it will hold your memory data.
2. Create a token. A GitHub fine-grained personal access token, scoped to only this repository, with Contents: Read and write.
3. Deploy to Vercel. Import the repo, set the environment variables, hit Deploy.

GITHUB_TOKEN=github_pat_...        # the token from step 2
GITHUB_REPO_OWNER=your-username
GITHUB_REPO_NAME=your-private-repo
# a provider key for the main model (OPENAI_API_KEY / ANTHROPIC_API_KEY / … pick one)
DEEPSEEK_API_KEY=sk-...            # powers the search colleague's web retrieval

Open the deployed URL and type your first message — it opens the first slice on your timeline. The cloud form has exactly one kind of brain: your own provider API key (BYOK), which is also the fullest experience.

Step-by-step detail, the access defense, and upgrades are in Deploy on Vercel.

Path two: run locally (npm)

Requirements: Node.js ≥ 22.13. No Docker, no git installation needed.

npm i -g @previously-lab/client
previously

Bare previously is the front door. On first run it walks you through an init wizard in the terminal:

1. Sets up the runtime — creates ~/.previously for kernel versions, logs, and process state.
2. Sets up your memory — creates your memory repository at ~/Documents/Previously; if a Previously repo already lives there (say, cloned back from a backup), it adopts it — history fully preserved.
3. Picks an engine — the recommended answer is your own provider API key (BYOK), identical to the cloud experience. The wizard also detects agent CLIs on your PATH (Claude Code, Codex, Kimi Code) and can bridge an existing subscription into an engine — zero extra cost, but it's a fallback: a bridged agent's behavior is beyond our control, and the experience can be noticeably short of BYOK. The trade-offs are in Two Engines.
4. Transcribes your existing history — turns your other local agents' existing conversation logs into slices on the timeline. This step costs zero tokens: transcription is deterministic parsing, not a model call.

Any step that would spend tokens shows you the estimate first and defaults to not running. Nothing quietly spends your money.

Once init finishes, bare previously becomes a status panel — what's running, where the memory repo lives, what to do next, all on one screen:

╭───────────────────────────────────────────────────────────────────────────────────────╮
│                                                                                       │
│ Home:      ~/.previously                                                              │
│ Config:    ~/.previously/config.json                                                  │
│ Kernel:    not running                                                                │
│ Version:   0.9.0 (pinned 0.9.0 — compatible, source: pointer)                         │
│ Port:      127.0.0.1:3210 unreachable                                                 │
│ Storage:   local (memory root: ~/Documents/Previously)                                │
│ Memory repo: main — clean, last commit 2026-08-28T05:23:38Z                           │
│ Backend:   claude                                                                     │
│   bridge claude: found (/usr/local/bin/claude)                                        │
│   bridge codex: not found — "codex" not on PATH                                       │
│   bridge kimi: found (~/.kimi-code/bin/kimi)                                          │
│ Scribe:    not running                                                                │
│   claude-code: 225/225 files, 0 events, 0 parse errors, last event —                  │
│   codex: ! root absent (~/.codex/sessions)                                            │
│   kimi-code: 227/227 files, 6 events, 0 parse errors, last event 2026-08-28T05:23:34Z │
│   gemini: ! root absent (~/.gemini/tmp)                                               │
│ Next:      run `previously start` to start the kernel                                 │
│                                                                                       │
╰───────────────────────────────────────────────────────────────────────────────────────╯

Start it and open it:

previously start   # start the kernel in the background
previously open    # open the Web UI in your browser

The Web UI lives at 127.0.0.1:3210 — reachable only from your own machine. No account creation, no database setup, no seed data.

Related

• Deploy on Vercel — the full walkthrough of the recommended path
• Local First — the thinking and current state of the local form
• Two Engines — the BYOK vs. bridge trade-off