beadless

⚡ The Problem

AI coding agents (Antigravity, Claude Code, Cursor, Windsurf) lose their memory between sessions. Every time you open a new conversation, clear context, or switch branches:

• Architectural decisions are forgotten.

• Past bugs and lessons are repeated.

• Complex multi-step task graphs get lost.

Beads introduced versioned agent memory, but requires a heavy Go binary and an external Dolt SQL database daemon running in the background.

beadless gives your agents persistent, dependency-aware memory stored as plain JSON and Markdown committed directly into your repository.

Related MCP server: Projectmem

🥊 Beads vs. beadless

🚀 30-Second Quickstart

In your repository root:

npx beadless init

That's it! beadless will scaffold .beadless/ and automatically configure your Antigravity, Cursor (.cursor/mcp.json), or Claude Desktop environment.

🪐 Attach to Google Antigravity

Add to your Antigravity MCP settings (~/.gemini/antigravity/mcp_config.json):

{
  "mcpServers": {
    "beadless": {
      "command": "npx",
      "args": ["-y", "beadless", "mcp"]
    }
  }
}

🤖 Attach to Claude Code

claude mcp add beadless npx -y beadless mcp

💻 Attach to Cursor / Windsurf

Add this to your MCP configuration (.cursor/mcp.json or settings):

{
  "mcpServers": {
    "beadless": {
      "command": "npx",
      "args": ["-y", "beadless", "mcp"]
    }
  }
}

🛠️ MCP Tools for Agents

When attached to an agent, beadless exposes these standard MCP tools:

• beadless_global_recall: Cross-session & cross-workspace search! Queries all recorded chats, global memories, and past Antigravity conversation transcripts for past discussions, decisions, and fixes.

• beadless_chat_save: Saves the current chat session's summary, decisions, and files touched into persistent isolated memory.

• beadless_chat_list: Lists past recorded chat sessions across workspaces.

• beadless_global_sync: Scans and indexes recent Antigravity transcripts into beadless global memory.

• beadless_context: Dumps instant project briefing (tech stack, conventions, critical gotchas, and top unblocked tasks).

• beadless_snapshot: Captures the current workspace state, modified/untracked files, and branch status into persistent memory.

• beadless_remember: Records an architectural decision, lesson, or preference.

• beadless_recall: Fuzzy-searches past decisions and gotchas in current project to avoid repeating mistakes.

• beadless_delete: Removes a memory entry by ID or semantic description.

• beadless_task_create: Adds a task with dependency tracking (blockedBy: ["task-1"]).

• beadless_task_claim: Claims a task for the active agent session.

• beadless_task_complete: Marks task complete and automatically unblocks downstream tasks.

• beadless_task_list: Queries tasks (e.g. --ready for unblocked tasks only).

💻 CLI Usage

You can also use beadless directly from your terminal:

🌐 Global Recall (Cross-Chat & Antigravity Intelligence)

# View overview of all recorded chats and Antigravity sessions
npx beadless global

# Search for any topic across all sessions, chats, and transcripts
npx beadless global "canvas font fix"
npx beadless global "gods-eye-view"
npx beadless global "auth overhaul"

💬 Multi-Chat Isolation & Session Management

# Save current session accomplishments & decisions
npx beadless chat save "Implemented OAuth flow" \
  --summary "Switched to PKCE with argon2 session storage" \
  --decisions "Use httpOnly cookies" \
  --tags auth oauth

# List recorded chat sessions across projects
npx beadless chat list

# Show details of a specific chat session
npx beadless chat show <chatId>

# Auto-sync recent Antigravity transcripts into beadless global index
npx beadless chat sync

Remember a Decision

npx beadless remember "Use Argon2 for password hashing" \
  --category decision \
  --message "Argon2id is memory-hard and prevents ASIC/GPU attacks." \
  --tags auth security

Snapshot Workspace State (Auto-Recording)

# Capture immediate snapshot with automatic title and timestamp (keeps all old memories!)
npx beadless snap

# Custom snapshot title with description
npx beadless snap "Completed authentication and cookies"

🗑️ Delete / Forget Memories

# Interactive list of recent memories
npx beadless del

# Delete by exact ID
npx beadless del mem-1234

# Smart semantic deletion (understands what you mean and deletes matching memory)
npx beadless del "eski veritabanı kararı"

⏱️ Automatic Periodic Auto-Recorder (Watcher)

# Automatically records changes every 10 minutes (default)
npx beadless watch

# Custom interval (every 5 minutes, triggers on >= 2 modified files)
npx beadless auto --interval 5 --min-changes 2 --immediate

Recall Memories

npx beadless recall "password"

Manage Task Dependency Graph

# 1. Create root task
npx beadless tasks create "Design database schema" --priority high

# 2. Create dependent task (blocked by task-1)
npx beadless tasks create "Build authentication API" --blocked-by task-1

# 3. View task board
npx beadless tasks list

# 4. Complete root task (unblocks task-2)
npx beadless tasks done task-1 --outcome "Prisma schema created"

Instant Agent Bootstrap

# Dump formatted project context to terminal or clipboard
npx beadless context

📂 Repository Layout

Everything is stored inside your repository under .beadless/:

your-repo/
├── .beadless/
│   ├── config.json         # beadless settings (auto-commit, prefix)
│   ├── memories.json       # Structured decisions, lessons, context
│   ├── MEMORIES.md         # Auto-generated human-readable memory log
│   ├── tasks.json          # Dependency graph (blockedBy, claimedBy)
│   ├── TASKS.md            # Auto-generated markdown task board
│   └── context.json        # Stack, conventions & non-negotiables

Because it lives in git:

• Branch-aware: Branches keep their own context or inherit from main.

• Team-shared: Every git pull updates your local agent's memory.

• Reviewable: You can see every AI agent decision in standard GitHub pull requests!

📜 License

MIT © KuraPiee — Built with ❤️ by the Docwyrm Team.