Workspace Memory

A persistent knowledge base scoped to each workspace. Workers save memories as they encounter gotchas, make decisions, or discover patterns. Future workers search this memory before starting work, avoiding repeated mistakes and building on prior knowledge.

Memory is backed by the Buildd Memory service. Each team gets an isolated memory store — memories are further scoped by project (workspace repo name) within the team. Memory keys are auto-provisioned on first use.

Setup

Memory works out of the box — no configuration needed. When a team first uses memory (via MCP or API), Buildd automatically provisions an isolated memory API key for the team and stores it. All subsequent memory operations use this team-scoped key.

For self-hosted runners: Memory is accessed through the Buildd API (/api/workspaces/:id/memory). As long as the Buildd server has MEMORY_API_URL and MEMORY_ROOT_KEY configured, memory auto-provisions for each team.

Memory Types

Each memory has a type that describes what kind of knowledge it captures:

How Workers Use Memory

Automatic Memory on Claim

When a worker claims a task via buildd action=claim_task, the server automatically searches memory using the task title and includes relevant memories in the response. Workers should read these before starting.

Loading Context

Workers should load project context at the start of a session:

buildd_memory action=context

This returns a markdown digest of recent memories for the current project.

Searching Before Work

Workers should search manually before touching unfamiliar files:

buildd_memory action=search params={ query: "drizzle schema migrations" }
buildd_memory action=search params={ type: "gotcha", files: ["packages/core/db/schema.ts"] }

Search supports:

• Text query — full-text search across titles and content
• Type filter — narrow to a specific memory type
• File filter — find memories referencing specific file paths
• Tag filter — search by tagged concepts
• Limit — control result count (default: 10, max: 50)

Search returns full memory content inline — no separate fetch step needed.

Saving Memories

Save memories immediately when you encounter something noteworthy — don't wait until the end of a task:

buildd_memory action=save params={
  type: "gotcha",
  title: "db.transaction() fails with neon-http driver",
  content: "Interactive transactions are not supported by the neon-http driver. Use atomic UPDATE...WHERE with .returning() for optimistic locking instead.",
  files: ["packages/core/db/schema.ts"],
  tags: ["drizzle", "neon", "transactions"]
}

Fields:

• type (required) — one of the six memory types
• title (required) — short, descriptive title
• content (required) — full details with context
• files (optional) — related file paths for searchability
• tags (optional) — tags for categorization

Updating Memories

Correct stale or inaccurate memories:

buildd_memory action=update params={
  id: "mem_xxx",
  content: "Updated: neon-http now supports transactions in v0.10+, but only with pool mode disabled."
}

Any field can be updated: title, content, type, files, tags.

Deleting Memories

Remove outdated memories that are no longer relevant:

buildd_memory action=delete params={ id: "mem_xxx" }

API Reference

Memory is accessed through workspace proxy routes that forward to the memory service:

List / Search Memories

GET /api/workspaces/{id}/memory?query=...&type=...&limit=10

Create Memory

POST /api/workspaces/{id}/memory
Content-Type: application/json

{
  "type": "gotcha",
  "title": "Short title",
  "content": "Full details...",
  "files": ["path/to/file.ts"],
  "tags": ["tag1", "tag2"]
}

Update Memory

PATCH /api/workspaces/{id}/memory/{memoryId}
Content-Type: application/json

{
  "title": "Updated title",
  "content": "Updated content..."
}

Delete Memory

DELETE /api/workspaces/{id}/memory/{memoryId}

All memory endpoints support dual authentication — both API key (Bearer token) and session auth.

MCP Server Usage

The buildd_memory tool exposes six actions:

Memory is also available as an MCP resource at buildd://workspace/memory, which returns recent memories for the workspace.