LOOM Blog

Project updates, architecture deep dives, and release notes. Follow along as we build the persistent context layer for AI agents.

What is LOOM?

LOOM is a semantic persistent context OS for AI coding agents like Claude Code and Kimi Code. Most AI assistants lose all context when a chat session ends. LOOM solves this by persisting tasks, decisions, code artifacts, and their relationships in a structured local knowledge base. Every time an agent starts a new session, LOOM injects a compact, cache-optimized prompt so the agent instantly knows where you left off.

It doesn't just store memory — it understands your project. LOOM tracks file freshness, builds import dependency graphs, and automatically flags stale, orphaned, or redundant code.

The Session Amnesia Problem

When you close a conversation with an AI coding assistant, the following vanishes:

  • Current tasks and their progress
  • Architecture decisions you just finalized
  • Files you're actively modifying
  • Why certain files are relevant

Next time, you have to explain everything again. For one-off questions, that's fine. For multi-day refactors or complex feature development, it's exhausting.

LOOM's Solution

LOOM persists four core elements across sessions:

  1. Tasks & Progress — What you're doing, what's done, what's blocked, what's next
  2. Decisions — Architectural choices that don't need to be re-debated as long as their premises hold
  3. Working Set — Files and rules relevant to the current task
  4. File System Health — What's fresh, what's stale, what's orphaned, and who depends on whom
92
Tests Passing
5
Packages
15+
MCP Tools
2.7MB
MCP Footprint

Architecture Overview

LOOM is structured as an npm workspace monorepo with five focused packages, each with a clear responsibility:

Package Purpose
@spongeacer/loom-core Types, StoreAdapter (FS + Memory), WAL queue, dependency graph, health analyzer, prompt builder, file tracking, watch daemon
@spongeacer/loom-cli Human-facing command-line interface with text formatting
@spongeacer/loom-mcp MCP Server with 15+ tools via stdio JSON-RPC
@spongeacer/loom-cloud Cloud sync, Ed25519 device identity, license validation, conflict resolution
loom-vscode VS Code extension for native IDE integration

Design Principles

  • No duplicate code — All business logic lives in loom-core; CLI and MCP are thin wrappers
  • Security without compromise — Ed25519 device identity with zero fallback; scrypt password hashing
  • Storage pluggability — StoreAdapter interface with FS and Memory implementations
  • Self-hostable cloud — Docker Compose on your own infrastructure, with user-isolated file storage

Read the full architecture doc on GitHub.

v0.4.0
2026-04-19

Self-Built JSON-RPC MCP Core

The biggest change in v0.4.0: we removed the @modelcontextprotocol/sdk dependency entirely and built our own bare JSON-RPC stdio implementation. The result is dramatic:

83ms
Cold Start
2.7MB
node_modules
0.86MB
Heap
149→83
ms Improvement

Highlights

  • Feature Complete Prompt Builder with all 11 slots: protocol, governance, decisions, dictionary, task, working_set, risks, recovery, recent_files, fs_health
  • Fix Chinese task ID collision — makeTaskSlug now appends a randomUUID suffix
  • Fix Watch daemon cross-project leak — stale PID cleanup prevents zombie daemons
  • Fix Store singleton cwd limitation — getStore(cwd?) enables true multi-project support
  • Fix Missing SIGPIPE handler added to prevent crashes on broken stdout
  • Feature First MCP test coverage with router.test.ts
  • Feature Cloud sync server deployed on Alibaba Cloud ECS with HTTPS
v0.3.0
2026-04-18

Monorepo Architecture Refactor

The entire codebase was restructured from a single package into a proper npm workspace monorepo with 5 focused packages. This was a foundational change that made everything after it possible.

Key Changes

  • Feature Business logic下沉 into @spongeacer/loom-core/src/commands/ — shared between CLI and MCP
  • Feature Full ESM with TypeScript Node16 module resolution
  • Feature exports field in package.json with types conditions
  • Security Removed fake Ed25519 fallback (deterministic SHA-512 seed). Zero fallback — crypto failure now throws
  • Breaking loom install-mcp command removed. MCP registration is now manual
  • Breaking Package name changed from loom-mcp to @spongeacer/loom-cli / @spongeacer/loom-mcp

52 tests, 0 failures across 15 suites at launch.

v0.2.0
2026-04-15

Store Transactions & Pure Commands

v0.2.0 introduced the transaction layer and decoupled all commands from the CLI runtime, laying the groundwork for the MCP integration that came later.

Highlights

  • Feature withStoreTransaction / withStoreTransactionAsync for atomic multi-step writes
  • Feature Pure commands — fully decoupled CLI from MCP runtime
  • Feature Daily diary generation (loom diary / loom_diary_generate)
  • Fix MCP hardening: withLock leak, async lock collapse, path traversal; graceful shutdown + WAL drain
  • Feature Full unit test coverage: 29 suites, 107 tests
  • Feature ESLint configuration & VS Code extension skeleton
v0.1.1
2026-04-14

Initial Stable Release

The first stable release of LOOM established the core concepts that still define the project today:

  • WAL (Write-Ahead Log) for event durability
  • Entries system: rules, memories, skills, patterns, artifacts, tasks, decisions
  • Cache layer with L1.5 summaries
  • Slot-based prompt builder
  • Task and Decision tracking

From these foundations, every subsequent release has built upward without rewriting the core abstraction.