Swamp

Type: ../types/agent-memory-system-review.md

Swamp, built by Elder Swamp Club, is a local-first automation CLI designed for AI coding agents. Agents use installed skills and repository instructions to turn a user's operational intent into typed model definitions and declarative workflows; Swamp then validates and executes those symbolic artifacts while retaining versioned observations, run records, reports, and audit material for later actions.

Repository: https://github.com/swamp-club/swamp

Reviewed commit: cf38c4ec1068613bb7d3432eb74a1ad854156dd7

Last checked: 2026-07-18

Core Ideas

Swamp turns agent interpretation into reviewable symbolic automation. Its agent-facing instructions route requests toward model types, model definitions, workflows, reports, and vaults instead of leaving the full procedure in an agent transcript. Model and workflow definitions persist as YAML in top-level repository directories; workflow objects have typed jobs, inputs, triggers, concurrency, and report selections, and the validator checks schemas, references, required arguments, uniqueness, and cycles before execution (src/domain/repo/repo_service.ts, src/domain/workflows/workflow.ts, src/domain/workflows/validation_service.ts). The remembered material changes future action directly: a retained workflow can schedule or repeat model methods without asking an LLM to reconstruct the sequence.

The repository separates durable definitions from operational observations. Git-tracked models/, workflows/, vaults/, and grants/ hold source-of-truth system definitions, while a datastore holds versioned model data, evaluated definitions, workflow runs, outputs, audit logs, and other runtime state. The default datastore is file-backed under .swamp/, with a SQLite catalog and run tracker used for indexed metadata and execution state; datastore extensions can move runtime state to another filesystem or S3 (design/high-level.md, design/repo.md, src/infrastructure/persistence/repository_factory.ts). This split gives authored policy normal git review while allowing runtime state to use lifecycle, synchronization, and locking policies appropriate to machine output.

Versioned data is operational memory, not just logging. Every data item carries ownership, tags, content type, lifetime, garbage-collection policy, checksum, and a monotonically allocated version. A plain-text latest marker promotes the newest version, and CEL expressions such as data.latest(...) let later model or workflow inputs depend on retained observations (src/domain/data/data.ts, src/infrastructure/persistence/unified_data_repository.ts, src/domain/data/data_query_service.ts). This can change a future action without re-contacting the external system, but freshness remains whatever the model method, schedule, and data lifetime establish; versioning alone does not make an observation current or correct.

Context efficiency comes from progressive disclosure and structured lookup. Agent harnesses always see compact repository rules and skill names/descriptions, then load the swamp skill, a topic guide, and deeper references only when the request requires them. Runtime state is not dumped into the prompt: agents query models, workflow history, reports, or data through scoped CLI commands, while DataQueryService evaluates CEL predicates over a SQLite metadata catalog and lazy-loads JSON content only when a predicate or projection needs attributes (.claude/skills/swamp/SKILL.md, design/skills.md, src/domain/data/data_query_service.ts). Volume is bounded by query limits and selective file loading; complexity is reduced by routing through model/workflow/data concepts, though a large skill reference tree or broad query can still impose substantial interpretation work.

Adoption uses native agent and repository surfaces, but instruction freshness is binary-managed. repo init writes per-repository CLAUDE.md, AGENTS.md, or tool-specific rules and settings, while bundled skills are copied into each enrolled tool's global skill directory and refreshed by init, upgrade, or Swamp update. Definitions remain inspectable YAML and extension code remains TypeScript, so users can diff and review the consequential artifacts without a metered memory service (src/domain/repo/repo_service.ts, design/global-skills.md). The tradeoff is that the active guidance comes from the installed binary's bundled copy and can be shadowed by stale project-local skills; Swamp detects that condition and warns, but effective agent compliance is not verified by the implementation.

Artifact analysis

  • Storage substrate: files repo sqlite — Git-tracked YAML, TypeScript extensions, instruction files, and repository configuration retain authored system definitions; file-backed datastore trees retain versioned content, workflow runs, outputs, reports, and audit logs; SQLite provides the metadata catalog and run tracker used to find and coordinate those file artifacts. Optional external datastore extensions change deployment storage, but not the reviewed default architecture.
  • Representational form: prose symbolic — Skills, generated agent rules, descriptions, report text, logs, and some model outputs are prose. YAML schemas and definitions, CEL expressions, tags, versions, checksums, lifecycle fields, workflow DAGs, grants, TypeScript model/report extensions, validators, indexes, and executable CLI code are symbolic. Swamp uses agents to author artifacts but does not retain model weights or adapters.
  • Lineage: authored imported other-compiled — Humans and agents author definitions, workflows, extensions, vault/grant configuration, and repository-specific instructions; model methods can import observations and files from external systems; evaluated definitions, version metadata, catalog rows, run records, method outputs, reports, generated instruction scaffolds, and installed skill copies are compiled from authored definitions, bundled assets, or already-retained runtime data. Their invalidators include definition changes, extension versions, source observations, repository upgrade state, and datastore mutations. No central retained artifact is derived from agent traces.
  • Behavioral authority: knowledge instruction enforcement routing validation ranking — Versioned data, reports, logs, and run history are knowledge artifacts available to agents, humans, and later CEL evaluation. Skills and repository rules instruct agents; workflows, grants, vault references, and model methods define or constrain execution; names, tags, dependencies, triggers, CEL references, and the CLI route work and data; schemas, workflow validation, ownership checks, approvals, and checksums enforce or validate contracts; latest markers and catalog fields rank one data version as the default read. The code does not assign a learning authority to run traces.

Model, workflow, vault, and grant definitions. These are file- and repo-backed system-definition artifacts. Their prose names and descriptions aid agent/human interpretation, while YAML structure, type versions, CEL expressions, workflow edges, schedules, grants, and vault references are symbolic inputs to validators and executors. YamlWorkflowRepository parses each file back through Workflow.fromData, so malformed or schema-invalid files do not silently become executable workflows (src/infrastructure/persistence/yaml_workflow_repository.ts).

Versioned model data and run artifacts. Model methods write raw bytes plus YAML metadata, size, checksum, owner, tags, lifetime, and version. Workflow runs and method outputs retain execution history separately. These are primarily knowledge artifacts: later commands, reports, CEL expressions, and operators can inspect them as evidence about external systems and prior runs. They can acquire routing force when data.latest(...) supplies a later method argument, but the stored observation is not itself a validated statement about the external world (src/domain/models/data_writer.ts, src/infrastructure/persistence/yaml_workflow_run_repository.ts).

Catalog, latest markers, and evaluated copies. SQLite catalog rows, latest marker files, and evaluated definition/workflow copies are symbolic access artifacts compiled from primary files and data versions. They make lookup and execution cheaper, but their authority depends on synchronization with the underlying artifact. The query service verifies an unpopulated catalog row against on-disk content and performs scoped or full backfill when needed, making the file data rather than a stale index row decisive (src/domain/data/data_query_service.ts).

Skills and generated repository instructions. The bundled swamp skill is a prose/symbolic system-definition package: its routing table selects topic guides, its rules prescribe tool use and validation, and its references progressively disclose command detail. RepoService materializes bundled skills globally and generates per-repository instructions that require model discovery and route automation requests through Swamp. Bundled source changes or a Swamp version update invalidate the installed copies; repo-local shadows can preserve stale authority until removed (.claude/skills/swamp/SKILL.md, src/domain/repo/repo_service.ts).

Promotion path. Swamp's important promotion is from natural-language intent to stronger system-definition authority: an agent follows prose skills, authors symbolic model/workflow YAML or TypeScript extensions, validates the result, and hands it to deterministic scheduling and execution. Execution then promotes each new observation to the latest data version and may feed it through CEL into later steps. This is codification and runtime compilation, not trace-learning: Swamp does not mine the agent conversation that produced the definition into a new retained rule.

Comparison with Our System

Swamp and Commonplace both make agent work inspectable by moving durable behavior out of chat and into repository artifacts with explicit structure. Both use progressive skill disclosure, native Markdown/YAML/code, validation, and version control. The central difference is what becomes authoritative: Commonplace primarily retains typed knowledge and methodology, with selected instructions and validators promoted to system-definition authority; Swamp is designed to compile intent into executable operational definitions whose schemas and runtime have direct effects on external systems.

Swamp's runtime data plane is also more active than Commonplace's library. Versioned observations can be selected by latest, queried by CEL, and wired into later methods or workflows. Commonplace retains review and source evidence but generally requires an agent to navigate and interpret it. Swamp gains repeatability and lower semantic recomputation for known automation, while paying for a datastore, lifecycle policy, locks, evaluated copies, and a larger synchronization surface.

The governance tradeoff is asymmetric. Swamp strongly validates symbolic shape, dependencies, ownership, and execution contracts, but it cannot infer from code whether an external observation is true or whether an agent chose the right model. Commonplace's semantic review is better suited to claim fidelity, while Swamp's executor is better suited to enforcing a settled procedure. In both systems, structural validation must not be mistaken for semantic verification.

Borrowable Ideas

Make promotion from advice to executable policy explicit. Ready now as an analysis pattern. Commonplace could describe more instruction/validator pairs as a visible progression from knowledge artifact to system-definition artifact, including the validation required before authority increases.

Use a source-of-truth plus rebuildable access-artifact contract. Ready now. Swamp's catalog backfill and on-disk verification are a useful model for Commonplace indexes and caches: derived lookup state should identify its primary artifacts and recover when stale rather than silently becoming a second authority.

Attach lifecycle policy to machine-produced artifacts at creation. Needs a concrete Commonplace runtime-data use case. Swamp records lifetime and version-retention policy with data instead of relying on later cleanup guesses. Commonplace could apply the same rule to high-volume workshop or review execution outputs, but durable library notes should not decay by recency.

Retain deterministic execution results separately from authored definitions. Ready for workflow infrastructure. Swamp keeps git-reviewable definitions distinct from run records and outputs; Commonplace review jobs already have a similar distinction and should preserve it when adding new automation.

Do not borrow latest as an unqualified truth signal. Swamp's marker is useful routing metadata, but recency is not epistemic validity. Any Commonplace analogue should keep freshness, review status, and substantive acceptance separate.

Write side

Write agency: manual automatic — Humans and agents author or edit models, workflows, extensions, reports, grants, and vault configuration through files and CLI commands. Model and workflow execution automatically writes evaluated copies, versioned data, run records, outputs, reports, audit events, catalog rows, checksums, and latest-version markers; optional autoGc applies configured data retention after method runs (design/repo.md, src/domain/models/data_writer.ts).

Curation operations: decay promote — Lifecycle GC can remove duration-expired, workflow/job-scoped, orphaned, or excess historical data versions, and autoGc makes policy-driven cleanup a post-run operation when enabled. Every successful new version updates the latest marker, promoting it to the default read without rewriting older content (src/domain/data/data_lifecycle_service.ts, src/infrastructure/persistence/unified_data_repository.ts). Run/output GC is manual-only at the reviewed commit. I found no automatic deduplication, in-place semantic evolution, contradiction invalidation, or cross-entry synthesis over retained memory.

Swamp's automatic writes are execution-derived, but they are not trace-learning. Workflow and method records describe a deterministic automation run; no inspected path treats an agent session, transcript, tool trace, event stream, or trajectory as training material from which it extracts a durable lesson, skill, rule, validator, or model update. CLAUDE.md asks contributors to propose session learnings, but that is manual direct authoring and does not establish a trace-distillation mechanism (CLAUDE.md).

Read-back

Read-back: pull — Retained Swamp memory reaches an agent when it deliberately runs model/data/workflow/report/history commands or reads repository YAML; generated baseline instructions and bundled skills tell the agent when and how to perform those lookups, but static shipped guidance is not accumulated memory and does not make the read-back path push.

The same retained artifacts also serve non-agent consumers. The workflow executor reads definitions and prior data directly, scheduled triggers can run without an agent context, reports and audit records serve human operators, and CEL expressions pull selected stored values into deterministic execution. This is operational consumption of retained state, but the reviewed harness does not automatically select and inject accumulated run data into an agent prompt. Retrieval quality and whether an agent follows the instruction to inspect relevant state are not verified from code.

Curiosity Pass

  • The README says, "All the data lives in the .swamp/ (the swamp)," but the implementation deliberately keeps source-of-truth definitions in top-level git-tracked directories and now installs bundled skills in user-global tool directories. The slogan is directionally about local ownership, not an accurate storage map (README.md, src/domain/repo/repo_service.ts).
  • Swamp calls itself "AI Native Automation," but the durable core is intentionally less agentic after authoring: YAML, CEL, schemas, DAG validation, and model methods remove recurring scheduling and bookkeeping from the LLM. Its strongest memory property is therefore codification, not recall sophistication.
  • latest is a cheap and deterministic selection policy that works well for state snapshots, but it can hide stale or semantically degraded observations behind a fresh version number. Checksums verify retained bytes, not external truth.
  • The generated instruction requires swamp model search --json at the start of every conversation. This is an explicit pull discipline rather than contextual activation: it spends a command to restore project orientation because the agent does not retain it across sessions (src/domain/repo/repo_service.ts).

What to Watch

  • The planned applications, environments, and drift detection would turn retained versions into automatic comparative evidence. If implemented, inspect whether drift becomes advisory knowledge, a workflow gate, or an auto-remediation trigger; those choices materially change behavioral authority (design/high-level.md).
  • RepoIndexService is currently a no-op event handler even though repositories emit mutation events. An event-driven index or context injector built on that surface could change Swamp from agent-disciplined pull to targeted push, making its selection signal and faithfulness tests relevant (design/repo.md).

Relevant Notes: