AMS (Agent Management System)

Version: 3.3.0 Status: Active Updated: 2026-02-16 Module: root

Deterministic agents for auditable work.

Project page: https://lasteld.github.io/AMS/

AMS is an MCP server that adds memory, audit integrity, and deterministic orchestration to AI-assisted development workflows.

What Is AMS

AMS is an Agent Management System for teams that want agent output to be:

• Stateful across sessions (not "chat-only memory")
• Auditable and tamper-evident
• Reproducible through explicit orchestration rules
• Safe to run with rollback and access controls

At runtime, AMS combines:

• Unified MCP tools (projects/unified-mcp)
• GSD pipeline integration (projects/get-shit-done)
• Educational roadmap system (data/roadmaps)
• Optional product layer UI/bridge (projects/ams-mcp-ui)

Why It Exists

Typical agent workflows fail in the same ways:

• No durable memory across sessions
• No reliable proof of what was changed and why
• Orchestration drift ("half works, half breaks")
• Unsafe file mutation without recovery path
• Weak onboarding because architecture intent is not explicit

AMS exists to solve those issues with one system:

• Memory frames + RAG indexing
• Action hash chain + Merkle audit proofs
• Deterministic phase pipeline
• Git checkpoint and rollback controls
• RBAC/ACL for project-scoped operations

Quick Start

1. Install dependencies:

cd projects/unified-mcp
npm install

2. Configure MCP client:

{
  "mcpServers": {
    "ams": {
      "command": "node",
      "args": ["C:/AMS/projects/unified-mcp/src/server.js"],
      "env": {
        "AMS_ROOT": "C:/AMS"
      }
    }
  }
}

3. Run smoke commands in your MCP client:

unified_vitals
unified_help
roadmap_list

If these three succeed, server routing, database, and roadmap loading are operational.

For release-grade validation in projects/unified-mcp:

npm test
npm run arch:gate
npm run pillars:gate:deep

Architecture and Phases

AMS uses two phase models.

1. Execution pipeline for autonomous runs:

INIT -> GATHER -> ANALYZE -> PLAN -> [DRY_RUN|APPLY] -> VERIFY -> DONE

2. Audit integrity phases:

• Phase 1: Context snapshots with SHA-256 verification
• Phase 2: Action hash chain
• Phase 3: Thought chain (decision trace)
• Phase 4: Merkle tree finalization
• Phase 5: Proof verification and audit export flow

Current status:

• Core phases are implemented and wired in the MCP server.
• Product/UI layer is available as a separate project (projects/ams-mcp-ui) and evolves independently.

Advanced Concepts

• Tool profiles and token economy:
  • AMS_TOOL_PROFILE=full|default|core|custom
  • AMS_TOOL_PROFILE_STRICT=true|false
• Orchestration dependency graph:
  • Mandatory pre/post chains (A -> B, A -> C, A -> D) are encoded in graph + workflow layer.
• Memory and retrieval:
  • analysis_rag_index, analysis_rag_search, memory_pack, memory_verify
• Safety controls:
  • Circuit breaker, retry/backoff, rate limiting, rollback
• Access control:
  • Project-scoped ACL via AMS_USER_ID and acl_* tools

Project Structure (JavaScript)

AMS/
|- projects/
|  |- unified-mcp/          # Main MCP server (controllers/domains/db/middleware)
|  |- get-shit-done/        # GSD planning/execution framework
|  `- ams-mcp-ui/           # Optional bridge server + dashboard UI
|- data/
|  |- ams.db                # SQLite runtime database
|  |- roadmaps/             # Learning roadmap content
|  `- state/                # Runtime mutable state files
|- docs/                    # Stable docs, planning, archive, ideas
|- scripts/ops/             # Operational verification/maintenance scripts
`- config/                  # Environment and integration configs

For developer onboarding and code-review orientation, start with docs/reference/DEVELOPER_GUIDE.md.

Documentation Map

• docs/reference/DEVELOPER_GUIDE.md - onboarding, architecture walkthrough, review flow
• SETUP_GUIDE.md - installation and MCP client setup
• USER_GUIDE.md - practical day-to-day tool usage
• DEPLOYMENT.md - production deployment and release checks
• docs/reference/PIPELINE_USAGE_GUIDE.md - autonomous pipeline operation
• docs/reference/AMS_QR_MEMORY.md - AMS-QR memory model
• docs/reference/COMMANDS.md - tool catalog
• ARCHITECTURAL_ANALYSIS.md - deep architectural trade-offs

Current Snapshot

• Version: 3.3.0
• Tools: use unified_help for live surface count
• Roadmaps: use roadmap_list for live count