Skip to content

AGENT.md

Latest commit

 

History

History
123 lines (86 loc) · 3.53 KB

AGENT.md

File metadata and controls

123 lines (86 loc) · 3.53 KB
Raw

AGENT.md

This file provides implementation and collaboration guidance for coding agents working in this repository.

Project Snapshot

  • Project: welder
  • Goal: local-first, transparent AI agent system with file-first memory and observable context management
  • Backend: FastAPI + LangChain 1.x (create_agent) + OpenAI-compatible model interface
  • Frontend: Next.js 14 + TypeScript + Tailwind + Monaco
  • Runtime ports: frontend 3000, backend 8002

Source-of-Truth Architecture (Current)

1) Memory & Workspace

Canonical memory paths are under backend/workspace:

  • backend/workspace/MEMORY.md (long-term memory)
  • backend/workspace/memory/logs/YYYY-MM-DD.md (daily logs)
  • backend/workspace/memory/index/memory.sqlite (retrieval index, acceleration layer only)

Do not introduce new runtime writes to legacy backend/memory/* paths.

2) Context Pipeline

Core orchestration lives in:

  • backend/context/manager.py
  • backend/context/* helpers (bootstrap.py, pruner.py, flush.py, compactor.py, token_budget.py)

Pipeline order before LLM call:

  1. load context state
  2. apply bootstrap limits
  3. token precheck
  4. prune aged tool results
  5. pre-compaction flush when needed
  6. compaction when needed
  7. return prepared system prompt + messages

3) Agent Runtime

  • backend/agent/agent_manager.py
  • Uses LangChain 1.x create_agent
  • Supports streaming SSE events: content, tool_call, complete, error
  • Handles overflow via compaction+retry
  • Persists session + updates long-term memory after assistant response

4) API Layer

  • backend/app.py
  • File API allowlist roots: workspace, skills, sessions
  • Rejects absolute paths and traversal (..)

Engineering Principles

  1. File-first truth: Markdown/JSON are authoritative; SQLite is rebuildable cache.
  2. Transparency over magic: prefer explicit state/events/logs to hidden behavior.
  3. Safety first: preserve strict path and command boundaries.
  4. OpenClaw alignment: keep workspace prompt components concise and ordered.
  5. Deterministic behavior: avoid brittle regex heuristics for core memory extraction.

Development Commands

Setup

uv sync
cd frontend && npm install && cd ..

Run

./start.sh

or manually:

uv run uvicorn backend.app:app --reload --port 8002
cd frontend && npm run dev

Validate

cd backend && pytest -q
cd frontend && npx tsc --noEmit

Key Files to Read First

  • README.md
  • docs/TECH_ARCHITECTURE.md
  • backend/app.py
  • backend/agent/agent_manager.py
  • backend/context/manager.py
  • backend/memory/memory_manager.py
  • backend/tools/core_tools.py

Guardrails for Future Changes

  • Keep public file API roots unchanged unless explicitly required and reviewed.
  • Keep memory extraction LLM-structured and schema-driven.
  • If changing context thresholds, update both context_config.py and docs.
  • Preserve SSE event compatibility (content/tool_call/complete/error).
  • Update docs (README.md, docs/TECH_ARCHITECTURE.md, this file) when behavior changes.

Known Realities / Non-Goals

  • backend/context/compactor.py currently uses a placeholder summarization strategy; it is not a full production summarizer yet.
  • Some historical dependencies may remain in pyproject.toml; avoid documenting unused stacks as active runtime dependencies.

When in Doubt

Follow this reasoning order:

  1. match current runtime code behavior
  2. preserve path safety and memory truth model
  3. keep context pipeline observable
  4. update docs in the same change