Skip to content

Getting started

This tutorial walks you through your first angelo session end to end: you'll scaffold a project, start the servers, and watch the agent bootstrap a knowledge graph. By the end you'll have a working, committed memory tree and know what each piece is for.

Before you begin

Install angelo first — follow Install Angelo. You'll need Cursor (or Claude Code) and a virtualenv with angelo on its PATH.

1. Scaffold the project

From your project root, with the venv active:

angelo init

Pick your editor when prompted. This writes the .cursor/ config (rules, MCP server definitions, agents) and a managed .gitignore block.

2. Start the servers

Open the project in Cursor. The MCP servers start automatically — check Settings → MCP for green indicators next to angelo-coordinator, angelo-memory, and the others.

If the servers don't start

Cursor launches the servers with its own PATH, not your shell's. If the angelo-* commands live in a venv Cursor can't see, run angelo doctor — it prints the absolute paths to drop into mcp.json.

3. Onboard the project

In your first chat, ask the agent to onboard the project. What happens depends on whether the repo is new or established:

  • A new (greenfield) project: the agent calls the memory server's create_project tool to bootstrap an empty research tree in .memory/, then you record entries as work happens.
  • An existing (brownfield) codebase with git history: the agent runs the bundled onboard-existing-codebase skill, which reconstructs how the codebase was built — it creates the project, reads a history(action="digest") of the repo's evolution, and persists a back-dated, reconstructed-tagged timeline via history(action="reconstruct") so recall is useful from day one. It's a git-derived approximation, not lived memory, so the agent will show you the proposed tree before writing it.

Once a tree exists, the onboard-project skill catches a fresh agent up on the current state in later sessions.

4. Commit the knowledge graph

Before you commit, ask the agent to record() a checkpoint (or decision) to memory — every git commit is preceded by a memory entry, so the record of what you did travels up with the code.

git add .cursor/ .memory/
git commit -m "chore: scaffold angelo"

.memory/ is the source of truth for your knowledge graph and persists across machines — committing it is what makes the memory durable.

What you just built

  • .cursor/ — rules, agent personas, and the MCP server config.
  • .memory/ — your research tree (the project root node, ready for entries).

Next steps